Package uinput is a pure go package that provides access to the userland input device driver uinput on linux systems. Virtual keyboard devices as well as virtual mouse input devices may be created using this package. The keycodes and other event definitions, that are available and can be used to trigger input events, are part of this package ("Key1" for number 1, for example). In order to use the virtual keyboard, you will need to follow these three steps: Initialize the device Example: vk, err := CreateKeyboard("/dev/uinput", "Virtual Keyboard") Send Button events to the device Example (print a single D): err = vk.KeyPress(uinput.KeyD) Example (keep moving right by holding down right arrow key): err = vk.KeyDown(uinput.KeyRight) Example (stop moving right by releasing the right arrow key): err = vk.KeyUp(uinput.KeyRight) Close the device Example: err = vk.Close() A virtual mouse input device is just as easy to create and use: Initialize the device: Example: vm, err := CreateMouse("/dev/uinput", "DangerMouse") Move the cursor around and issue click events Example (move mouse right): err = vm.MoveRight(42) Example (move mouse left): err = vm.MoveLeft(42) Example (move mouse up): err = vm.MoveUp(42) Example (move mouse down): err = vm.MoveDown(42) Example (trigger a left click): err = vm.LeftClick() Example (trigger a right click): err = vm.RightClick() Close the device Example: err = vm.Close() If you'd like to use absolute input events (move the cursor to specific positions on screen), use the touch pad. Note that you'll need to specify the size of the screen area you want to use when you initialize the device. Here are a few examples of how to use the virtual touch pad: Initialize the device: Example: vt, err := CreateTouchPad("/dev/uinput", "DontTouchThis", 0, 1024, 0, 768) Move the cursor around and issue click events Example (move cursor to the top left corner of the screen): err = vt.MoveTo(0, 0) Example (move cursor to the position x: 100, y: 250): err = vt.MoveTo(100, 250) Example (trigger a left click): err = vt.LeftClick() Example (trigger a right click): err = vt.RightClick() Close the device Example: err = vt.Close()
Package oauth1 is a Go implementation of the OAuth1 spec RFC 5849. It allows end-users to authorize a client (consumer) to access protected resources on their behalf (e.g. login) and allows clients to make signed and authorized requests on behalf of a user (e.g. API calls). It takes design cues from golang.org/x/oauth2, providing an http.Client which handles request signing and authorization. Package oauth1 implements the OAuth1 authorization flow and provides an http.Client which can sign and authorize OAuth1 requests. To implement "Login with X", use the https://github.com/dghubble/gologin packages which provide login handlers for OAuth1 and OAuth2 providers. To call the Twitter, Digits, or Tumblr OAuth1 APIs, use the higher level Go API clients. * https://github.com/dghubble/go-twitter * https://github.com/dghubble/go-digits * https://github.com/benfb/go-tumblr Perform the OAuth 1 authorization flow to ask a user to grant an application access to his/her resources via an access token. 1. When a user performs an action (e.g. "Login with X" button calls "/login" route) get an OAuth1 request token (temporary credentials). 2. Obtain authorization from the user by redirecting them to the OAuth1 provider's authorization URL to grant the application access. Receive the callback from the OAuth1 provider in a handler. 3. Acquire the access token (token credentials) which can later be used to make requests on behalf of the user. Check the examples to see this authorization flow in action from the command line, with Twitter PIN-based login and Tumblr login. Use an access Token to make authorized requests on behalf of a user. Check the examples to see Twitter and Tumblr requests in action.
Package oauth1 is a Go implementation of the OAuth1 spec RFC 5849. It allows end-users to authorize a client (consumer) to access protected resources on their behalf (e.g. login) and allows clients to make signed and authorized requests on behalf of a user (e.g. API calls). It takes design cues from golang.org/x/oauth2, providing an http.Client which handles request signing and authorization. Package oauth1 implements the OAuth1 authorization flow and provides an http.Client which can sign and authorize OAuth1 requests. To implement "Login with X", use the https://github.com/dghubble/gologin packages which provide login handlers for OAuth1 and OAuth2 providers. To call the Twitter, Digits, or Tumblr OAuth1 APIs, use the higher level Go API clients. * https://github.com/dghubble/go-twitter * https://github.com/dghubble/go-digits * https://github.com/benfb/go-tumblr Perform the OAuth 1 authorization flow to ask a user to grant an application access to his/her resources via an access token. 1. When a user performs an action (e.g. "Login with X" button calls "/login" route) get an OAuth1 request token (temporary credentials). 2. Obtain authorization from the user by redirecting them to the OAuth1 provider's authorization URL to grant the application access. Receive the callback from the OAuth1 provider in a handler. 3. Acquire the access token (token credentials) which can later be used to make requests on behalf of the user. Check the examples to see this authorization flow in action from the command line, with Twitter PIN-based login and Tumblr login. Use an access Token to make authorized requests on behalf of a user. Check the examples to see Twitter and Tumblr requests in action.
Package gochrome aims to be a complete Chrome DevTools Protocol Viewer implementation. Versioned packages are available. Curently the only version is `tot` or Tip-of-Tree. Stable versions will be made available in the future. This is beta software and hasn't been well exercised in real-world applications. See https://chromedevtools.github.io/devtools-protocol/ The Chrome DevTools Protocol allows for tools to instrument, inspect, debug and profile Chromium, Chrome and other Blink-based browsers. Many existing projects currently use the protocol. The Chrome DevTools uses this protocol and the team maintains its API. Instrumentation is divided into a number of domains (DOM, Debugger, Network etc.). Each domain defines a number of commands it supports and events it generates. Both commands and events are serialized JSON objects of a fixed structure. You can either debug over the wire using the raw messages as they are described in the corresponding domain documentation, or use extension JavaScript API. The latest (tip-of-tree) protocol (tot) It changes frequently and can break at any time. However it captures the full capabilities of the Protocol, whereas the stable release is a subset. There is no backwards compatibility support guaranteed for the capabilities it introduces. Resources Basics: Using DevTools as protocol client The Developer Tools front-end can attach to a remotely running Chrome instance for debugging. For this scenario to work, you should start your host Chrome instance with the remote-debugging-port command line switch: Then you can start a separate client Chrome instance, using a distinct user profile: Now you can navigate to the given port from your client and attach to any of the discovered tabs for debugging: http://localhost:9222 You will find the Developer Tools interface identical to the embedded one and here is why: In this scenario, you can substitute Developer Tools front-end with your own implementation. Instead of navigating to the HTML page at http://localhost:9222, your application can discover available pages by requesting: http://localhost:9222/json and getting a JSON object with information about inspectable pages along with the WebSocket addresses that you could use in order to start instrumenting them. Remote debugging is especially useful when debugging remote instances of the browser or attaching to the embedded devices. Blink port owners are responsible for exposing debugging connections to the external users. This is especially handy to understand how the DevTools frontend makes use of the protocol. First, run Chrome with the debugging port open: Then, select the Chromium Projects item in the Inspectable Pages list. Now that DevTools is up and fullscreen, open DevTools to inspect it. Cmd-R in the new inspector to make the first restart. Now head to Network Panel, filter by Websocket, select the connection and click the Frames tab. Now you can easily see the frames of WebSocket activity as you use the first instance of the DevTools. To allow chrome extensions to interact with the protocol, we introduced chrome.debugger extension API that exposes this JSON message transport interface. As a result, you can not only attach to the remotely running Chrome instance, but also instrument it from its own extension. Chrome Debugger Extension API provides a higher level API where command domain, name and body are provided explicitly in the `sendCommand` call. This API hides request ids and handles binding of the request with its response, hence allowing `sendCommand` to report result in the callback function call. One can also use this API in combination with the other Extension APIs. If you are developing a Web-based IDE, you should implement an extension that exposes debugging capabilities to your page and your IDE will be able to open pages with the target application, set breakpoints there, evaluate expressions in console, live edit JavaScript and CSS, display live DOM, network interaction and any other aspect that Developer Tools is instrumenting today. Opening embedded Developer Tools will terminate the remote connection and thus detach the extension. https://chromedevtools.github.io/devtools-protocol/#simultaneous The canonical protocol definitions live in the Chromium source tree: (browser_protocol.json and js_protocol.json). They are maintained manually by the DevTools engineering team. These files are mirrored (hourly) on GitHub in the devtools-protocol repo. The declarative protocol definitions are used across tools. Within Chromium, a binding layer is created for the Chrome DevTools to interact with, and separately the protocol is used for Chrome Headless’s C++ interface. What’s the protocol_externs file It’s created via generate_protocol_externs.py and useful for tools using closure compiler. The TypeScript story is here. Not yet. See bugger-daemon’s third-party docs. See also the endpoints implementation in Chromium. /json/protocol was added in Chrome 60. The endpoint is exposed as webSocketDebuggerUrl in /json/version. Note the browser in the URL, rather than page. If Chrome was launched with --remote-debugging-port=0 and chose an open port, the browser endpoint is written to both stderr and the DevToolsActivePort file in browser profile folder. Yes, as of Chrome 63! See Multi-client remote debugging support. Upon disconnnection, the outgoing client will receive a detached event. For example: View the enum of possible reasons. (For reference: the original patch). After disconnection, some apps have chosen to pause their state and offer a reconnect button.
Package tui is a library for building user interfaces for the terminal. Widgets are the main building blocks of any user interface. They allow us to present information and interact with our application. It receives keyboard and mouse events from the terminal and draws a representation of itself. Widgets are structured using layouts. Layouts are powerful tools that let you position your widgets without having to specify their exact coordinates. Here, the VBox will ensure that the Button will be placed underneath the Label. There are currently three layouts to choose from; VBox, HBox and Grid. Sizing of widgets is controlled by its SizePolicy. For now, you can read more about how size policies work in the Qt docs: http://doc.qt.io/qt-5/qsizepolicy.html#Policy-enum
Package uinput is a pure go package that provides access to the userland input device driver uinput on linux systems. Virtual keyboard devices as well as virtual mouse input devices may be created using this package. The keycodes and other event definitions, that are available and can be used to trigger input events, are part of this package ("Key1" for number 1, for example). In order to use the virtual keyboard, you will need to follow these three steps: Initialize the device Example: vk, err := CreateKeyboard("/dev/uinput", "Virtual Keyboard") Send Button events to the device Example (print a single D): err = vk.KeyPress(uinput.KeyD) Example (keep moving right by holding down right arrow key): err = vk.KeyDown(uinput.KeyRight) Example (stop moving right by releasing the right arrow key): err = vk.KeyUp(uinput.KeyRight) Close the device Example: err = vk.Close() A virtual mouse input device is just as easy to create and use: Initialize the device: Example: vm, err := CreateMouse("/dev/uinput", "DangerMouse") Move the cursor around and issue click events Example (move mouse right): err = vm.MoveRight(42) Example (move mouse left): err = vm.MoveLeft(42) Example (move mouse up): err = vm.MoveUp(42) Example (move mouse down): err = vm.MoveDown(42) Example (trigger a left click): err = vm.LeftClick() Example (trigger a right click): err = vm.RightClick() Close the device Example: err = vm.Close() If you'd like to use absolute input events (move the cursor to specific positions on screen), use the touch pad. Note that you'll need to specify the size of the screen area you want to use when you initialize the device. Here are a few examples of how to use the virtual touch pad: Initialize the device: Example: vt, err := CreateTouchPad("/dev/uinput", "DontTouchThis", 0, 1024, 0, 768) Move the cursor around and issue click events Example (move cursor to the top left corner of the screen): err = vt.MoveTo(0, 0) Example (move cursor to the position x: 100, y: 250): err = vt.MoveTo(100, 250) Example (trigger a left click): err = vt.LeftClick() Example (trigger a right click): err = vt.RightClick() Close the device Example: err = vt.Close()
Package oauth1 is a Go implementation of the OAuth1 spec RFC 5849. It allows end-users to authorize a client (consumer) to access protected resources on their behalf (e.g. login) and allows clients to make signed and authorized requests on behalf of a user (e.g. API calls). It takes design cues from golang.org/x/oauth2, providing an http.Client which handles request signing and authorization. Package oauth1 implements the OAuth1 authorization flow and provides an http.Client which can sign and authorize OAuth1 requests. To implement "Login with X", use the https://github.com/dghubble/gologin packages which provide login handlers for OAuth1 and OAuth2 providers. To call the Twitter, Digits, or Tumblr OAuth1 APIs, use the higher level Go API clients. * https://github.com/dghubble/go-twitter * https://github.com/dghubble/go-digits * https://github.com/benfb/go-tumblr Perform the OAuth 1 authorization flow to ask a user to grant an application access to his/her resources via an access token. 1. When a user performs an action (e.g. "Login with X" button calls "/login" route) get an OAuth1 request token (temporary credentials). 2. Obtain authorization from the user by redirecting them to the OAuth1 provider's authorization URL to grant the application access. Receive the callback from the OAuth1 provider in a handler. 3. Acquire the access token (token credentials) which can later be used to make requests on behalf of the user. Check the examples to see this authorization flow in action from the command line, with Twitter PIN-based login and Tumblr login. Use an access Token to make authorized requests on behalf of a user. Check the examples to see Twitter and Tumblr requests in action.
Package tui is a library for building user interfaces for the terminal. Widgets are the main building blocks of any user interface. They allow us to present information and interact with our application. It receives keyboard and mouse events from the terminal and draws a representation of itself. Widgets are structured using layouts. Layouts are powerful tools that let you position your widgets without having to specify their exact coordinates. Here, the VBox will ensure that the Button will be placed underneath the Label. There are currently three layouts to choose from; VBox, HBox and Grid. Sizing of widgets is controlled by its SizePolicy. For now, you can read more about how size policies work in the Qt docs: http://doc.qt.io/qt-5/qsizepolicy.html#Policy-enum
Package govuegui provides a simple gui, which can be used via a http server inside the browser. There are three different elements for building the gui. Every level gets a identifier as a string. First level is the Form. Every Form has one submit button. A form can have boxes. It depends on the implementation how the boxes are rendered. Inside of a box the fields are defined. The api let's you define everything on a very simple way: The gui will be show up inside the browser of the user as a webapp. The app uses vuejs with a websocket connection.
Package oauth1 is a Go implementation of the OAuth1 spec RFC 5849. It allows end-users to authorize a client (consumer) to access protected resources on their behalf (e.g. login) and allows clients to make signed and authorized requests on behalf of a user (e.g. API calls). It takes design cues from golang.org/x/oauth2, providing an http.Client which handles request signing and authorization. Package oauth1 implements the OAuth1 authorization flow and provides an http.Client which can sign and authorize OAuth1 requests. To implement "Login with X", use the https://github.com/dghubble/gologin packages which provide login handlers for OAuth1 and OAuth2 providers. To call the Twitter, Digits, or Tumblr OAuth1 APIs, use the higher level Go API clients. * https://github.com/dghubble/go-twitter * https://github.com/dghubble/go-digits * https://github.com/benfb/go-tumblr Perform the OAuth 1 authorization flow to ask a user to grant an application access to his/her resources via an access token. 1. When a user performs an action (e.g. "Login with X" button calls "/login" route) get an OAuth1 request token (temporary credentials). 2. Obtain authorization from the user by redirecting them to the OAuth1 provider's authorization URL to grant the application access. Receive the callback from the OAuth1 provider in a handler. 3. Acquire the access token (token credentials) which can later be used to make requests on behalf of the user. Check the examples to see this authorization flow in action from the command line, with Twitter PIN-based login and Tumblr login. Use an access Token to make authorized requests on behalf of a user. Check the examples to see Twitter and Tumblr requests in action.
Package be2bill implements client access to the Be2bill merchant API defined at http://developer.be2bill.com/API. Every initial transaction is made using a secure form. The Form Client API exposes methods that return the HTML code for payment or authorization buttons. The first step is to build a client for the given environment, using your credentials: To build a payment form button, call: Authorization form buttons are created similarly, except that the method to call is `BuildAuthorizationFormButton` that takes the same parameters. An authorization must be captured using the `Capture` method of the Direct Link Client API. All operations that do not require interactive data input from the client can be made using HTTP POST calls to the be2bill servers. The Direct Link Client API is an abstraction layer for these calls. Just like the Form Client API, the first step is to build a client for the given environment, using your credentials: Then, for example to capture a previously authorized transaction, call: Please note that access to the Direct Link Client API is not enabled by default. This service can only be activated by your account manager based on specific criteria. Please contact him or the support team for more information.
Package oauth1 is a Go implementation of the OAuth1 spec RFC 5849. It allows end-users to authorize a client (consumer) to access protected resources on their behalf (e.g. login) and allows clients to make signed and authorized requests on behalf of a user (e.g. API calls). It takes design cues from golang.org/x/oauth2, providing an http.Client which handles request signing and authorization. Package oauth1 implements the OAuth1 authorization flow and provides an http.Client which can sign and authorize OAuth1 requests. To implement "Login with X", use the https://github.com/dghubble/gologin packages which provide login handlers for OAuth1 and OAuth2 providers. To call the Twitter, Digits, or Tumblr OAuth1 APIs, use the higher level Go API clients. * https://github.com/dghubble/go-twitter * https://github.com/dghubble/go-digits * https://github.com/benfb/go-tumblr Perform the OAuth 1 authorization flow to ask a user to grant an application access to his/her resources via an access token. 1. When a user performs an action (e.g. "Login with X" button calls "/login" route) get an OAuth1 request token (temporary credentials). 2. Obtain authorization from the user by redirecting them to the OAuth1 provider's authorization URL to grant the application access. Receive the callback from the OAuth1 provider in a handler. 3. Acquire the access token (token credentials) which can later be used to make requests on behalf of the user. Check the examples to see this authorization flow in action from the command line, with Twitter PIN-based login and Tumblr login. Use an access Token to make authorized requests on behalf of a user. Check the examples to see Twitter and Tumblr requests in action.
Package uinput is a pure go package that provides access to the userland input device driver uinput on linux systems. Virtual keyboard devices as well as virtual mouse input devices may be created using this package. The keycodes and other event definitions, that are available and can be used to trigger input events, are part of this package ("Key1" for number 1, for example). In order to use the virtual keyboard, you will need to follow these three steps: Initialize the device Example: vk, err := CreateKeyboard("/dev/uinput", "Virtual Keyboard") Send Button events to the device Example (print a single D): err = vk.KeyPress(uinput.KeyD) Example (keep moving right by holding down right arrow key): err = vk.KeyDown(uinput.KeyRight) Example (stop moving right by releasing the right arrow key): err = vk.KeyUp(uinput.KeyRight) Close the device Example: err = vk.Close() A virtual mouse input device is just as easy to create and use: Initialize the device: Example: vm, err := CreateMouse("/dev/uinput", "DangerMouse") Move the cursor around and issue click events Example (move mouse right): err = vm.MoveRight(42) Example (move mouse left): err = vm.MoveLeft(42) Example (move mouse up): err = vm.MoveUp(42) Example (move mouse down): err = vm.MoveDown(42) Example (trigger a left click): err = vm.LeftClick() Example (trigger a right click): err = vm.RightClick() Close the device Example: err = vm.Close() If you'd like to use absolute input events (move the cursor to specific positions on screen), use the touch pad. Note that you'll need to specify the size of the screen area you want to use when you initialize the device. Here are a few examples of how to use the virtual touch pad: Initialize the device: Example: vt, err := CreateTouchPad("/dev/uinput", "DontTouchThis", 0, 1024, 0, 768) Move the cursor around and issue click events Example (move cursor to the top left corner of the screen): err = vt.MoveTo(0, 0) Example (move cursor to the position x: 100, y: 250): err = vt.MoveTo(100, 250) Example (trigger a left click): err = vt.LeftClick() Example (trigger a right click): err = vt.RightClick() Close the device Example: err = vt.Close()
Package gochrome aims to be a complete Chrome DevTools Protocol Viewer implementation. Versioned packages are available. Curently the only version is `tot` or Tip-of-Tree. Stable versions will be made available in the future. This is beta software and hasn't been well exercised in real-world applications. See https://chromedevtools.github.io/devtools-protocol/ The Chrome DevTools Protocol allows for tools to instrument, inspect, debug and profile Chromium, Chrome and other Blink-based browsers. Many existing projects currently use the protocol. The Chrome DevTools uses this protocol and the team maintains its API. Instrumentation is divided into a number of domains (DOM, Debugger, Network etc.). Each domain defines a number of commands it supports and events it generates. Both commands and events are serialized JSON objects of a fixed structure. You can either debug over the wire using the raw messages as they are described in the corresponding domain documentation, or use extension JavaScript API. The latest (tip-of-tree) protocol (tot) It changes frequently and can break at any time. However it captures the full capabilities of the Protocol, whereas the stable release is a subset. There is no backwards compatibility support guaranteed for the capabilities it introduces. Resources Basics: Using DevTools as protocol client The Developer Tools front-end can attach to a remotely running Chrome instance for debugging. For this scenario to work, you should start your host Chrome instance with the remote-debugging-port command line switch: Then you can start a separate client Chrome instance, using a distinct user profile: Now you can navigate to the given port from your client and attach to any of the discovered tabs for debugging: http://localhost:9222 You will find the Developer Tools interface identical to the embedded one and here is why: In this scenario, you can substitute Developer Tools front-end with your own implementation. Instead of navigating to the HTML page at http://localhost:9222, your application can discover available pages by requesting: http://localhost:9222/json and getting a JSON object with information about inspectable pages along with the WebSocket addresses that you could use in order to start instrumenting them. Remote debugging is especially useful when debugging remote instances of the browser or attaching to the embedded devices. Blink port owners are responsible for exposing debugging connections to the external users. This is especially handy to understand how the DevTools frontend makes use of the protocol. First, run Chrome with the debugging port open: Then, select the Chromium Projects item in the Inspectable Pages list. Now that DevTools is up and fullscreen, open DevTools to inspect it. Cmd-R in the new inspector to make the first restart. Now head to Network Panel, filter by Websocket, select the connection and click the Frames tab. Now you can easily see the frames of WebSocket activity as you use the first instance of the DevTools. To allow chrome extensions to interact with the protocol, we introduced chrome.debugger extension API that exposes this JSON message transport interface. As a result, you can not only attach to the remotely running Chrome instance, but also instrument it from its own extension. Chrome Debugger Extension API provides a higher level API where command domain, name and body are provided explicitly in the `sendCommand` call. This API hides request ids and handles binding of the request with its response, hence allowing `sendCommand` to report result in the callback function call. One can also use this API in combination with the other Extension APIs. If you are developing a Web-based IDE, you should implement an extension that exposes debugging capabilities to your page and your IDE will be able to open pages with the target application, set breakpoints there, evaluate expressions in console, live edit JavaScript and CSS, display live DOM, network interaction and any other aspect that Developer Tools is instrumenting today. Opening embedded Developer Tools will terminate the remote connection and thus detach the extension. https://chromedevtools.github.io/devtools-protocol/#simultaneous The canonical protocol definitions live in the Chromium source tree: (browser_protocol.json and js_protocol.json). They are maintained manually by the DevTools engineering team. These files are mirrored (hourly) on GitHub in the devtools-protocol repo. The declarative protocol definitions are used across tools. Within Chromium, a binding layer is created for the Chrome DevTools to interact with, and separately the protocol is used for Chrome Headless’s C++ interface. What’s the protocol_externs file It’s created via generate_protocol_externs.py and useful for tools using closure compiler. The TypeScript story is here. Not yet. See bugger-daemon’s third-party docs. See also the endpoints implementation in Chromium. /json/protocol was added in Chrome 60. The endpoint is exposed as webSocketDebuggerUrl in /json/version. Note the browser in the URL, rather than page. If Chrome was launched with --remote-debugging-port=0 and chose an open port, the browser endpoint is written to both stderr and the DevToolsActivePort file in browser profile folder. Yes, as of Chrome 63! See Multi-client remote debugging support. Upon disconnnection, the outgoing client will receive a detached event. For example: View the enum of possible reasons. (For reference: the original patch). After disconnection, some apps have chosen to pause their state and offer a reconnect button.
This example opens https://github.com/, searches for "git", and then gets the header element which gives the description for Git. Rod use https://golang.org/pkg/context to handle cancelations for IO blocking operations, most times it's timeout. Context will be recursively passed to all sub-methods. For example, methods like Page.Context(ctx) will return a clone of the page with the ctx, all the methods of the returned page will use the ctx if they have IO blocking operations. Page.Timeout or Page.WithCancel is just a shortcut for Page.Context. Of course, Browser or Element works the same way. Shows how we can further customize the browser with the launcher library. Usually you use launcher lib to set the browser's command line flags (switches). Doc for flags: https://peter.sh/experiments/chromium-command-line-switches Shows how to change the retry/polling options that is used to query elements. This is useful when you want to customize the element query retry logic. When rod doesn't have a feature that you need. You can easily call the cdp to achieve it. List of cdp API: https://github.com/go-rod/rod/tree/master/lib/proto Shows how to disable headless mode and debug. Rod provides a lot of debug options, you can set them with setter methods or use environment variables. Doc for environment variables: https://pkg.go.dev/github.com/go-rod/rod/lib/defaults We use "Must" prefixed functions to write example code. But in production you may want to use the no-prefix version of them. About why we use "Must" as the prefix, it's similar to https://golang.org/pkg/regexp/#MustCompile Shows how to share a remote object reference between two Eval Shows how to listen for events. Shows how to intercept requests and modify both the request and the response. The entire process of hijacking one request: The --req-> and --res-> are the parts that can be modified. Show how to handle multiple results of an action. Such as when you login a page, the result can be success or wrong password. Example_search shows how to use Search to get element inside nested iframes or shadow DOMs. It works the same as https://developers.google.com/web/tools/chrome-devtools/dom#search Shows how to update the state of the current page. In this example we enable the network domain. Rod uses mouse cursor to simulate clicks, so if a button is moving because of animation, the click may not work as expected. We usually use WaitStable to make sure the target isn't changing anymore. When you want to wait for an ajax request to complete, this example will be useful.
Package main is an HTTP server that works with Github hooks. (Goreadme) https://github.com/posener/goreadme is a tool for creating README.md files from Go doc of a given package. This project is the Github app on top of this tool. It fully automates the process of keeping the README.md file updated. 1. Go to https://github.com/apps/goreadme. 2. Press the "Configure" button. 3. Choose your account, or an organization that owns the repository. 4. Review the permissions and provide access to goreadme to repositories. 5. Click Save. You should see PRs from goreadme bot in your github repos. For more features, or to trigger goreadme on demand, use the (Goreadme website) https://goreadme.herokuapp.com. Once integrated with a repository, goreadme is registered on a Github hook, that calls goreadme server whenever the repository default branch is modified. Goreadme then computes the new README.md file and compairs it to the exiting one. If a change is needed, Goreadme will create a PR with the new content of the README.md file. Adding a `goreadme.json` file to your repository main directory can enable some customization to the generated readme file. The configuration is available according to (goreadme.Config struct) https://godoc.org/github.com/posener/goreadme#Config.
Package oauth1 is a Go implementation of the OAuth1 spec RFC 5849. It allows end-users to authorize a client (consumer) to access protected resources on their behalf (e.g. login) and allows clients to make signed and authorized requests on behalf of a user (e.g. API calls). It takes design cues from golang.org/x/oauth2, providing an http.Client which handles request signing and authorization. Package oauth1 implements the OAuth1 authorization flow and provides an http.Client which can sign and authorize OAuth1 requests. To implement "Login with X", use the https://github.com/dghubble/gologin packages which provide login handlers for OAuth1 and OAuth2 providers. To call the Twitter, Digits, or Tumblr OAuth1 APIs, use the higher level Go API clients. * https://github.com/dghubble/go-twitter * https://github.com/dghubble/go-digits * https://github.com/benfb/go-tumblr Perform the OAuth 1 authorization flow to ask a user to grant an application access to his/her resources via an access token. 1. When a user performs an action (e.g. "Login with X" button calls "/login" route) get an OAuth1 request token (temporary credentials). 2. Obtain authorization from the user by redirecting them to the OAuth1 provider's authorization URL to grant the application access. Receive the callback from the OAuth1 provider in a handler. 3. Acquire the access token (token credentials) which can later be used to make requests on behalf of the user. Check the examples to see this authorization flow in action from the command line, with Twitter PIN-based login and Tumblr login. Use an access Token to make authorized requests on behalf of a user. Check the examples to see Twitter and Tumblr requests in action.
Package oauth1 is a Go implementation of the OAuth1 spec RFC 5849. It allows end-users to authorize a client (consumer) to access protected resources on their behalf (e.g. login) and allows clients to make signed and authorized requests on behalf of a user (e.g. API calls). It takes design cues from golang.org/x/oauth2, providing an http.Client which handles request signing and authorization. Package oauth1 implements the OAuth1 authorization flow and provides an http.Client which can sign and authorize OAuth1 requests. To implement "Login with X", use the https://github.com/dghubble/gologin packages which provide login handlers for OAuth1 and OAuth2 providers. To call the Twitter, Digits, or Tumblr OAuth1 APIs, use the higher level Go API clients. * https://github.com/dghubble/go-twitter * https://github.com/dghubble/go-digits * https://github.com/benfb/go-tumblr Perform the OAuth 1 authorization flow to ask a user to grant an application access to his/her resources via an access token. 1. When a user performs an action (e.g. "Login with X" button calls "/login" route) get an OAuth1 request token (temporary credentials). 2. Obtain authorization from the user by redirecting them to the OAuth1 provider's authorization URL to grant the application access. Receive the callback from the OAuth1 provider in a handler. 3. Acquire the access token (token credentials) which can later be used to make requests on behalf of the user. Check the examples to see this authorization flow in action from the command line, with Twitter PIN-based login and Tumblr login. Use an access Token to make authorized requests on behalf of a user. Check the examples to see Twitter and Tumblr requests in action.
Package oauth1 is a Go implementation of the OAuth1 spec RFC 5849. It allows end-users to authorize a client (consumer) to access protected resources on their behalf (e.g. login) and allows clients to make signed and authorized requests on behalf of a user (e.g. API calls). It takes design cues from golang.org/x/oauth2, providing an http.Client which handles request signing and authorization. Package oauth1 implements the OAuth1 authorization flow and provides an http.Client which can sign and authorize OAuth1 requests. To implement "Login with X", use the https://github.com/dghubble/gologin packages which provide login handlers for OAuth1 and OAuth2 providers. To call the Twitter, Digits, or Tumblr OAuth1 APIs, use the higher level Go API clients. * https://github.com/dghubble/go-twitter * https://github.com/dghubble/go-digits * https://github.com/benfb/go-tumblr Perform the OAuth 1 authorization flow to ask a user to grant an application access to his/her resources via an access token. 1. When a user performs an action (e.g. "Login with X" button calls "/login" route) get an OAuth1 request token (temporary credentials). 2. Obtain authorization from the user by redirecting them to the OAuth1 provider's authorization URL to grant the application access. Receive the callback from the OAuth1 provider in a handler. 3. Acquire the access token (token credentials) which can later be used to make requests on behalf of the user. Check the examples to see this authorization flow in action from the command line, with Twitter PIN-based login and Tumblr login. Use an access Token to make authorized requests on behalf of a user. Check the examples to see Twitter and Tumblr requests in action.
Package oauth1 is a Go implementation of the OAuth1 spec RFC 5849. It allows end-users to authorize a client (consumer) to access protected resources on their behalf (e.g. login) and allows clients to make signed and authorized requests on behalf of a user (e.g. API calls). It takes design cues from golang.org/x/oauth2, providing an http.Client which handles request signing and authorization. Package oauth1 implements the OAuth1 authorization flow and provides an http.Client which can sign and authorize OAuth1 requests. To implement "Login with X", use the https://github.com/dghubble/gologin packages which provide login handlers for OAuth1 and OAuth2 providers. To call the Twitter, Digits, or Tumblr OAuth1 APIs, use the higher level Go API clients. * https://github.com/dghubble/go-twitter * https://github.com/dghubble/go-digits * https://github.com/benfb/go-tumblr Perform the OAuth 1 authorization flow to ask a user to grant an application access to his/her resources via an access token. 1. When a user performs an action (e.g. "Login with X" button calls "/login" route) get an OAuth1 request token (temporary credentials). 2. Obtain authorization from the user by redirecting them to the OAuth1 provider's authorization URL to grant the application access. Receive the callback from the OAuth1 provider in a handler. 3. Acquire the access token (token credentials) which can later be used to make requests on behalf of the user. Check the examples to see this authorization flow in action from the command line, with Twitter PIN-based login and Tumblr login. Use an access Token to make authorized requests on behalf of a user. Check the examples to see Twitter and Tumblr requests in action.
Package ui is a simple package which provides a way to write portable GUI programs quickly and easily. It aims to run on as many systems as Go itself, but presently has support for Windows, Mac OS X, and other Unix systems using the Windows API, Cocoa, and GTK+ 3, respectively. It also aims to be Go-like: events are transmitted via channels, and the library is fully safe for concurrent use. To use the library, place your main program code in another function and call Go(), passing that function as a parameter. (This is necessary due to threading restrictions on some environments, such as Cocoa.) Once in the function you pass to Go(), you can safely use the rest of the library. When this function returns, so does Go(), and package functions become unavailable. Building GUIs is as simple as creating a Window, populating it with Controls, and then calling Open() on the Window. A Window only has one Control: you pack multiple Controls into a Window by arranging them in layouts (Layouts are also Controls). There are presently two Layouts, Stack and Grid, each with different semantics on sizing and placement. See their documentation. Once a Window is open, you cannot make layout or event channel changes. Once your Window is open, you can begin to handle events. Handling events is simple: because all events are channels exposed as exported members of the Window and Control types, simply select on them. Event channels are initialized by default. However, before you Open a Window, you can freely reassign event channels, such that multiple events trigger the same channel, making event logic more compact. You may also choose not to handle events; events are sent asynchronously so the GUI loop is not initerrupted. Here is a simple, complete program that asks the user for their name and greets them after clicking a button.
Package duit is a pure go, cross-platform, MIT-licensed, UI toolkit for developers. The examples/ directory has small code examples for working with duit and its UIs. Examples are the recommended starting point. Start with NewDUI to create a DUI: essentially a window and all the UI state. The user interface consists of a hierarchy of "UIs" like Box, Scroll, Button, Label, etc. They are called UIs, after the interface UI they all implement. The zero structs for UIs have sane default behaviour so you only have to fill in the fields you need. UIs are kept/wrapped in a Kid, to track their layout/draw state. Use NewKids() to build up the UIs for your application. You won't see much of the Kid-types/functions otherwise, unless you implement a new UI. You are in charge of the main event loop, receiving mouse/keyboard/window events from the dui.Inputs channel, and typically passing them on unchanged to dui.Input. All callbacks and functions on UIs are called from inside dui.Input. From there you can also safely change the the UIs, no locking required. After changing a UI you are responsible for calling MarkLayout or MarkDraw to tell duit the UI needs a new layout or draw. This may sound like more work, but this tradeoff keeps the API small and easy to use. If you need to change the UI from a goroutine outside of the main loop, e.g. for blocking calls, you can send a function that makes those modifications on the dui.Call channel, which will be run on the main channel through dui.Inputs. After handling an input, duit will layout or draw as necessary, no need to render explicitly. Embedding a UI into your own data structure is often an easy way to build up UI hiearchies. Scroll and Edit show a scrollbar. Use button 1 on the scrollbar to scroll up, button 3 to scroll down. If you click more near the top, you scroll less. More near the bottom, more. Button 2 scrolls to the absolute place, where you clicked. Button 4 and 5 are wheel up and wheel down, and also scroll less/more depending on position in the UI.
Package rod is a high-level driver directly based on DevTools Protocol. This example opens https://github.com/, searches for "git", and then gets the header element which gives the description for Git. Rod use https://golang.org/pkg/context to handle cancellations for IO blocking operations, most times it's timeout. Context will be recursively passed to all sub-methods. For example, methods like Page.Context(ctx) will return a clone of the page with the ctx, all the methods of the returned page will use the ctx if they have IO blocking operations. Page.Timeout or Page.WithCancel is just a shortcut for Page.Context. Of course, Browser or Element works the same way. Shows how we can further customize the browser with the launcher library. Usually you use launcher lib to set the browser's command line flags (switches). Doc for flags: https://peter.sh/experiments/chromium-command-line-switches Shows how to change the retry/polling options that is used to query elements. This is useful when you want to customize the element query retry logic. When rod doesn't have a feature that you need. You can easily call the cdp to achieve it. List of cdp API: https://github.com/apedem/rod/tree/master/lib/proto Shows how to disable headless mode and debug. Rod provides a lot of debug options, you can set them with setter methods or use environment variables. Doc for environment variables: https://pkg.go.dev/github.com/apedem/rod/lib/defaults We use "Must" prefixed functions to write example code. But in production you may want to use the no-prefix version of them. About why we use "Must" as the prefix, it's similar to https://golang.org/pkg/regexp/#MustCompile Shows how to share a remote object reference between two Eval Shows how to listen for events. Shows how to intercept requests and modify both the request and the response. The entire process of hijacking one request: The --req-> and --res-> are the parts that can be modified. Show how to handle multiple results of an action. Such as when you login a page, the result can be success or wrong password. Example_search shows how to use Search to get element inside nested iframes or shadow DOMs. It works the same as https://developers.google.com/web/tools/chrome-devtools/dom#search Shows how to update the state of the current page. In this example we enable the network domain. Rod uses mouse cursor to simulate clicks, so if a button is moving because of animation, the click may not work as expected. We usually use WaitStable to make sure the target isn't changing anymore. When you want to wait for an ajax request to complete, this example will be useful.
Package oauth1 is a Go implementation of the OAuth1 spec RFC 5849. It allows end-users to authorize a client (consumer) to access protected resources on their behalf (e.g. login) and allows clients to make signed and authorized requests on behalf of a user (e.g. API calls). It takes design cues from golang.org/x/oauth2, providing an http.Client which handles request signing and authorization. Package oauth1 implements the OAuth1 authorization flow and provides an http.Client which can sign and authorize OAuth1 requests. To implement "Login with X", use the https://github.com/dghubble/gologin packages which provide login handlers for OAuth1 and OAuth2 providers. To call the Twitter, Digits, or Tumblr OAuth1 APIs, use the higher level Go API clients. * https://github.com/dghubble/go-twitter * https://github.com/dghubble/go-digits * https://github.com/benfb/go-tumblr Perform the OAuth 1 authorization flow to ask a user to grant an application access to his/her resources via an access token. 1. When a user performs an action (e.g. "Login with X" button calls "/login" route) get an OAuth1 request token (temporary credentials). 2. Obtain authorization from the user by redirecting them to the OAuth1 provider's authorization URL to grant the application access. Receive the callback from the OAuth1 provider in a handler. 3. Acquire the access token (token credentials) which can later be used to make requests on behalf of the user. Check the examples to see this authorization flow in action from the command line, with Twitter PIN-based login and Tumblr login. Use an access Token to make authorized requests on behalf of a user. Check the examples to see Twitter and Tumblr requests in action.
Package tui is a library for building user interfaces for the terminal. Widgets are the main building blocks of any user interface. They allow us to present information and interact with our application. It receives keyboard and mouse events from the terminal and draws a representation of itself. Widgets are structured using layouts. Layouts are powerful tools that let you position your widgets without having to specify their exact coordinates. Here, the VBox will ensure that the Button will be placed underneath the Label. There are currently three layouts to choose from; VBox, HBox and Grid. Sizing of widgets is controlled by its SizePolicy. For now, you can read more about how size policies work in the Qt docs: http://doc.qt.io/qt-5/qsizepolicy.html#Policy-enum
* ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git) * ExaVault API * * # Introduction Welcome to the ExaVault API documentation. Our API lets you control nearly all aspects of your ExaVault account programatically, from uploading and downloading files to creating and managing shares and notifications. Capabilities of the API include - Uploading and downloading files. - Managing files and folders, including standard operations like move, copy and delete. - Getting information about activity occuring in your account. - Creating, updating and deleting users. - Creating and managing shares, including download-only shares and receive folders. - Setting up and managing notifications. The ExaVault API v2.0 is a RESTful API using JSON. ## The API URL You will access your account from your server address. For example, if your account is available at exampleaccount.exavault.com, you'll connect to the API at https://exampleaccount.exavault.com/api/v2 # Obtaining Your API Key and Access Token Account admins can create API Keys and personal access tokens within the ExaVault File Manager web application. ## Create an API Key 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 2. Click on the **My Account** option in the left-hand sidebar 3. Click on the **Developer** tab 4. Click the + button next to the table of API Keys to create a new key 5. Enter a name that will uniquely identify connections using this key. This name will appear in your activity session logs. 6. Enter a description with any other information that you need to track the purpose of your API key 7. Save the new key As soon as you save a new API key, you'll be prompted to create a personal access token which will allow a specific user to connect via the API using that API key (jump to step 5 in the instructions below) ## Generate an Access Token 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **My Account** option in the left-hand sidebar 1. Click on the **Developer** tab 1. Click the + button next to the table of Access Tokens to create a new token 1. Select the API Key from the first dropdown. 1. Select the user who will use this token from the second dropdown. 1. Click the **GENERATE TOKEN** button The confirmation popup will display your API key and your access token. **Copy this access token to a safe location (such as a password vault) immediately.** Once you close this popup, you will not be able to see the token again. After you have saved your token securely, click CLOSE to close the popup. The access token you have created will allow any program using that token and its API key to masquerade as the associated user. You should keep the token safe. # Authentication The ExaVault API uses the combination of an API key and a persistent access token to authenticate a user. Both the API key and the access token can be created by an admin-level user Each request made to the API must include 2 headers | Header Name | Contains | | --- | :---: | | **ev-api-key** | Your API key | | **ev-access-token** | Your access token | The access token uniquely identifies the user account for the connection. You should keep this token secure. # HTTP Status Codes The ExaVault API v2.0 is RESTful and returns appropriate HTTP status codes in its responses **Success Statuses:** | Status | Notes | | --- | :---: | | 200 | Successful operation | | 201 | Successful creation operation | | 207 | Multiple operation status | **Request Error Statuses:** | Status | Notes | | --- | :---: | | 400 | Bad Request | | 401 | Unauthorized | | 403 | Forbidden | | 404 | Not Found* | | 429 | Too many requests | **Server Error Statuses:** | Status | Notes | | --- | --- | | 500 | Server Error | | 503 | Service unavailable | # Response Format Nearly every response from the server will be a JSON object, which will contain a `responseStatus` attribute that matches the HTTP status of the response. Most succesful responses will also include a `data` attribute that contains the data related to your request. For instance using GET /account will return the information for the account associated with your API key and access token. ## Error Responses Error responses will have a similar format. The response will contain a `responseStatus` which contains the HTTP status code and an `errors` array, which will contain pertinent errors for the request. Each object in the `errors` array will contain a human-readable `code` and some explanatory `detail` text. ## Common Errors As you work with our suite of APIs, you'll likely encounter one or more of these error codes throughout the process. Let's take a look at some of the most common errors and how to resolve them quickly and painlessly. ### 400 Error - Bad Request: ```json { \"responseStatus\":400, \"errors\":[ { \"code\":\"ERROR_INVALID_PARAMETER\", \"detail\":\"Destination path cannot be an existing folder.\" } ] } ``` ```json { \"responseStatus\": 400, \"errors\": [ { \"code\": \"ERROR_INVALID_PASSWORD\", \"detail\": \"Password must be longer than eight (8) characters and contain one uppercase letter, one lowercase letter, and one number.\" } ] } ``` This error will generally mean a paramater or body element is invalid or missing. We suggest taking another look at the documentation of the API endpoint you're hitting to double check for; missing required fields in the request, spelling errors, invalid values be used. The error messaging returned should point you exactly to what you need to correct to avoid going through trial and error. ### 401 Error - Unauthorized ```json { \"responseStatus\": 401, \"errors\": [ { \"code\": \"ERROR_INVALID_CREDENTIALS\", \"detail\": \"HTTP_UNAUTHORIZED\" } ] } ``` If you encounter a 401, it means we're not recognizing the credentials you're attempting to authenticate with. To resolve the issue; 1. Double check that your credenitals (API Key and Access Token) are correct. 2. Creating a second set of credentials (see \"Obtaining Your API Key and Access Token\" above) and attempt the call again. 3. If you're able to successfully make a call, regenerate the Access Token of the first user and try the call one last time. If you're still encountering a 401, contact us for help. ### 403 Error - Forbidden ```json { \"responseStatus\": 403, \"errors\": [ { \"code\": \"ERROR_INSUFFICIENT_PRIVILEGES\", \"detail\": \"An error occurred\" } ] } ``` Similarly to a 401, you'll be unable to complete an API call if you encounter this error. Unlike a 401, your credentials were authenticated, but the authenticated user does not have permission to perform the action you're attempting. To resolve the issue you can either; - Execute the call using an master user's credentials. - Log in to the ExaVault File Manager OR use the **PATCH /updateUser** endpoint to update the user's permissions. ### 404 Error - Not Found ```json { \"responseStatus\": 404, \"errors\": [ { \"code\": \"ERROR_SHARE_NOT_FOUND\", \"detail\": \"Share not found\" } ] } ``` Encountering a 404 error means whatever type of resource you're attempting to find or update; isn't being found. Usually, this is just a case of using the wrong ID when using a call, and can be resolved by fixing the ID on your call. If the ID on the call appears to be correct we recommend taking the following steps: - Attempt a more generic GET call to get a list of the type of resource you're looking for to see if you can find the ID you're looking for. - Check your activity logs to see if what you're looking for was recently deleted. # Identifying Resources Many API methods require you to provide one or more resources, which may be expressed as paths, ids, hashes, or some combination of the three (for calls that act upon multiple resources). To specify a resource by path, provide a fully qualified string to the resource _relative to the associated user's home directory_. This path will always begin with a forward slash. Only forward slash characters may be used to separate the folders within a path string. To specify a resource by ID, you'll need to obtain that ID from some other API method first. For example, **GET /resources/list** will return a list of resources in your account along with their IDs. Once you have the ID of that resource, append it to the string \"id:\" to specify that resource, such as `id:124447`. IDs are always whole-number numeric values. To specify a resource by hash, first obtain the hash from another API method. Once you have the hash representing the resource, append it to the string \"hash:\" to specify that resource, such as `hash:3a1597ca982231f6666c75bcc2bd9c85` to indicate the resource with the hash value **3a1597ca982231f6666c75bcc2bd9c85**. Hashes are always an alphanumeric sequence without any special characters or punctuation. ## Paths and Home Folders Users with different home folders will use different paths to refer to the same resource. As an example, suppose there is a file located at **_/Data/Production/Inbound/1595978053_G12.xml**. For an admin-level user, or any user whose home folder permits them access to the entire account, the path for that resource is **_/Data/Production/Inbound/1595978053_G12.xml**. For a user whose home folder is **_/Data/Production/_**, the path to the file becomes **_/Inbound/1595978053_G12.xml** # Transaction Limits The daily transaction limit restricts the overall number of operations you can perform in a 24-hour period in your ExaVault account. Those transactions could be file uploads, file downloads, making a shared folder, creating a user, deleting files, to name a few examples. All operations performed in your account count against the total daily transactions for your account, including: - FTP/SFTP operations - Actions by users who are logged into your web interface - Interacting with Receive folders - Receiving files through Send files and Shared Folders - Accessing files shared through direct links - API access from any user using any of the API keys for your account Each request sent to the API is one transaction. When your account has exceeded its rolling 24-hour rate limit, new operations will become available once the number of operations in the past 24-hours is below your daily rate limit. The response status of rate-limited API operations will be **429**. ## Rate Limit Headers To monitor your daily account transaction usage, the response object returned by the server for all API requests will include these custom headers: - **X-RateLimit-Limit** indicates the total number of operations permitted within a rolling 24-hour period across your entire account. This number is dependent upon the plan your account is subscribed to, and whether you have an enterprise agreement in place. - **X-RateLimit-Remaining** indicates the number of operations currently remaning to you at that moment in time. # Webhooks ExaVault provides a webhook system for notifying you of changes to your account. The webhook sender will send a POST request to an endpoint you have specified whenever certain actions happen within your account. Account administrators can change these settings within the ExaVault File Manager. Webhooks will attempt to send a message up to 8 times with increasing timeouts between each attempt. All webhook requests are tracked in the webhooks log within the ExaVault File Manager web interface. ## Configuring Webhooks 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password. 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Add the URL where your webhook listener can receive requests 1. Check the boxes for the actions which should trigger your webhook. 1. Scroll to the bottom of the page to click SAVE SETTINGS. ## Verification Signature When you configure a webhook endpoint and triggering actions, a Verification Token will be displayed below the webhook endpoint URL. You may use this token in combination with the X-Exavault-Signature header to verify that ExaVault is the sender of the webhook request. ## Comparing the Signature You'll can use this 3-step procedure to validate an individual webhook request to ensure it was sent by ExaVault. **1: Get Verification Token** In order to verify the X-Exavault-Signature header value, you'll first need to obtain the Verification Token for your account: 1. Click on the **My Account** option in the left-hand sidebar. 1. Click on the **Developer** tab 1. Copy the Verification Token that appears below the Webhooks Endpoint url field. Every webhook request sent to your endpoint URL will use the same verification token. This token won't change for your account. **2: Concatenate Token and Request** Once you have the verification token, you'll concatenate that token along with the raw string representing the request body that was received. **Do not convert the request body to any other type** of object; if the library you're using automatically converts the request body to an object, look for a method to obtain the raw request body as text. **3: Calculate MD5 Hash** Calculate the md5 hash of that concatenation. The result should match the contents of your X-Exavault-Signature header. ## Webhook Request Examples The following examples demonstrate the structure of webhook requests and how to validate the verification signature for an individual request. All of these examples will use the same verification token; you'll need to use the token for your account to do the same checks on your own webhook requests. **User Connect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 6e13eb14edfd0bd54feff96be131e155 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Connect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **User Disconnect Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | 186e8c73793666c8b5cfa0b55eee691d | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Disconnect\",\"protocol\":\"web\",\"path\":\"\",\"sourcepath\":\"\",\"attempt\":1} ``` **File Upload Example** | Verification Token | X-Exavault-Signature header value | | --- | --- | | efb7e0030e6cef1b45d3d74a67881a2b | e86119ce1b679c7b6010d9ac9a843a36 | ```json {\"accountname\":\"exampleaccount\",\"username\":\"exampleaccount\",\"operation\":\"Upload\",\"protocol\":\"web\",\"path\":\"/7df2beb1c50a8a066493ee47669a4319.jpg\",\"sourcepath\":\"\",\"attempt\":1} ``` ## Webhooks Logs Account administrators can track all of the webhook requests sent for your account within the ExaVault File Manager web interface. To access Webhook logs: 1. Log into the ExaVault File Manager at your account name address. i.e., if your account is exampleaccount.exavault.com, go to https://exampleaccount.exavault.com and log in with your username and password 1. Click on the **Activity** option in the left-hand sidebar 1. Click on **Webhooks Logs** The webhook logs will show each time a webhook request was sent to your endpoint URL. The following information is recorded for each request: - date and time - when the system sent the request - endpoint url - where the webhook request was sent - event - what triggered the webhook - status - HTTP status or curl error code returned by the webhook endpoint - attempt - how many times this request has been sent - response size - size of the response from your webhook endpoint - details - the response body returned from your webhook endpoint * * API version: 2.0 * Generated by: Swagger Codegen (https://github.com/swagger-api/swagger-codegen.git)
Package oauth1 is a Go implementation of the OAuth1 spec RFC 5849. It allows end-users to authorize a client (consumer) to access protected resources on their behalf (e.g. login) and allows clients to make signed and authorized requests on behalf of a user (e.g. API calls). It takes design cues from golang.org/x/oauth2, providing an http.Client which handles request signing and authorization. Package oauth1 implements the OAuth1 authorization flow and provides an http.Client which can sign and authorize OAuth1 requests. To implement "Login with X", use the https://github.com/dghubble/gologin packages which provide login handlers for OAuth1 and OAuth2 providers. To call the Twitter, Digits, or Tumblr OAuth1 APIs, use the higher level Go API clients. * https://github.com/dghubble/go-twitter * https://github.com/dghubble/go-digits * https://github.com/benfb/go-tumblr Perform the OAuth 1 authorization flow to ask a user to grant an application access to his/her resources via an access token. 1. When a user performs an action (e.g. "Login with X" button calls "/login" route) get an OAuth1 request token (temporary credentials). 2. Obtain authorization from the user by redirecting them to the OAuth1 provider's authorization URL to grant the application access. Receive the callback from the OAuth1 provider in a handler. 3. Acquire the access token (token credentials) which can later be used to make requests on behalf of the user. Check the examples to see this authorization flow in action from the command line, with Twitter PIN-based login and Tumblr login. Use an access Token to make authorized requests on behalf of a user. Check the examples to see Twitter and Tumblr requests in action.
Package uinput is a pure go package that provides access to the userland input device driver uinput on linux systems. Virtual keyboard devices as well as virtual mouse input devices may be created using this package. The keycodes and other event definitions, that are available and can be used to trigger input events, are part of this package ("Key1" for number 1, for example). In order to use the virtual keyboard, you will need to follow these three steps: Initialize the device Example: vk, err := CreateKeyboard("/dev/uinput", "Virtual Keyboard") Send Button events to the device Example (print a single D): err = vk.KeyPress(uinput.KeyD) Example (keep moving right by holding down right arrow key): err = vk.KeyDown(uinput.KeyRight) Example (stop moving right by releasing the right arrow key): err = vk.KeyUp(uinput.KeyRight) Close the device Example: err = vk.Close() A virtual mouse input device is just as easy to create and use: Initialize the device: Example: vm, err := CreateMouse("/dev/uinput", "DangerMouse") Move the cursor around and issue click events Example (move mouse right): err = vm.MoveRight(42) Example (move mouse left): err = vm.MoveLeft(42) Example (move mouse up): err = vm.MoveUp(42) Example (move mouse down): err = vm.MoveDown(42) Example (trigger a left click): err = vm.LeftClick() Example (trigger a right click): err = vm.RightClick() Close the device Example: err = vm.Close() If you'd like to use absolute input events (move the cursor to specific positions on screen), use the touch pad. Note that you'll need to specify the size of the screen area you want to use when you initialize the device. Here are a few examples of how to use the virtual touch pad: Initialize the device: Example: vt, err := CreateTouchPad("/dev/uinput", "DontTouchThis", 0, 1024, 0, 768) Move the cursor around and issue click events Example (move cursor to the top left corner of the screen): err = vt.MoveTo(0, 0) Example (move cursor to the position x: 100, y: 250): err = vt.MoveTo(100, 250) Example (trigger a left click): err = vt.LeftClick() Example (trigger a right click): err = vt.RightClick() Close the device Example: err = vt.Close()
Package sogenactif provides support for the online payment solution provided by la Société Générale. https://www.sogenactif.com/ Load a config file with LoadConfig() then initialize the framework: Given a <merchant_id>, a NewSogen() call will check that the merchant's certificate is available in ${merchants_rootdir}/<merchant_id> (see conf/demo.cfg) and will create (or overwrite) some files required by the Sogenactif plateform: Now, using the API is a matter of serving content and calling Checkout() to initiate a payment, then calling HandlePayment() to get results back from the payment server. Initiate a payment with: Handle the return_url after a successful payment (provided the user click on the "return to site" button): Also handle the cancel_url in case a payment is cancelled: Finally, serve static content (to display credit card logos etc.) with:
Package button is a driver allowing to read the state of a button Display button status each time the button state changes
Package gochrome aims to be a complete Chrome DevTools Protocol Viewer implementation. Versioned packages are available. Curently the only version is `tot` or Tip-of-Tree. Stable versions will be made available in the future. This is beta software and hasn't been well exercised in real-world applications. See https://chromedevtools.github.io/devtools-protocol/ The Chrome DevTools Protocol allows for tools to instrument, inspect, debug and profile Chromium, Chrome and other Blink-based browsers. Many existing projects currently use the protocol. The Chrome DevTools uses this protocol and the team maintains its API. Instrumentation is divided into a number of domains (DOM, Debugger, Network etc.). Each domain defines a number of commands it supports and events it generates. Both commands and events are serialized JSON objects of a fixed structure. You can either debug over the wire using the raw messages as they are described in the corresponding domain documentation, or use extension JavaScript API. The latest (tip-of-tree) protocol (tot) It changes frequently and can break at any time. However it captures the full capabilities of the Protocol, whereas the stable release is a subset. There is no backwards compatibility support guaranteed for the capabilities it introduces. Resources Basics: Using DevTools as protocol client The Developer Tools front-end can attach to a remotely running Chrome instance for debugging. For this scenario to work, you should start your host Chrome instance with the remote-debugging-port command line switch: Then you can start a separate client Chrome instance, using a distinct user profile: Now you can navigate to the given port from your client and attach to any of the discovered tabs for debugging: http://localhost:9222 You will find the Developer Tools interface identical to the embedded one and here is why: In this scenario, you can substitute Developer Tools front-end with your own implementation. Instead of navigating to the HTML page at http://localhost:9222, your application can discover available pages by requesting: http://localhost:9222/json and getting a JSON object with information about inspectable pages along with the WebSocket addresses that you could use in order to start instrumenting them. Remote debugging is especially useful when debugging remote instances of the browser or attaching to the embedded devices. Blink port owners are responsible for exposing debugging connections to the external users. This is especially handy to understand how the DevTools frontend makes use of the protocol. First, run Chrome with the debugging port open: Then, select the Chromium Projects item in the Inspectable Pages list. Now that DevTools is up and fullscreen, open DevTools to inspect it. Cmd-R in the new inspector to make the first restart. Now head to Network Panel, filter by Websocket, select the connection and click the Frames tab. Now you can easily see the frames of WebSocket activity as you use the first instance of the DevTools. To allow chrome extensions to interact with the protocol, we introduced chrome.debugger extension API that exposes this JSON message transport interface. As a result, you can not only attach to the remotely running Chrome instance, but also instrument it from its own extension. Chrome Debugger Extension API provides a higher level API where command domain, name and body are provided explicitly in the `sendCommand` call. This API hides request ids and handles binding of the request with its response, hence allowing `sendCommand` to report result in the callback function call. One can also use this API in combination with the other Extension APIs. If you are developing a Web-based IDE, you should implement an extension that exposes debugging capabilities to your page and your IDE will be able to open pages with the target application, set breakpoints there, evaluate expressions in console, live edit JavaScript and CSS, display live DOM, network interaction and any other aspect that Developer Tools is instrumenting today. Opening embedded Developer Tools will terminate the remote connection and thus detach the extension. https://chromedevtools.github.io/devtools-protocol/#simultaneous The canonical protocol definitions live in the Chromium source tree: (browser_protocol.json and js_protocol.json). They are maintained manually by the DevTools engineering team. These files are mirrored (hourly) on GitHub in the devtools-protocol repo. The declarative protocol definitions are used across tools. Within Chromium, a binding layer is created for the Chrome DevTools to interact with, and separately the protocol is used for Chrome Headless’s C++ interface. What’s the protocol_externs file It’s created via generate_protocol_externs.py and useful for tools using closure compiler. The TypeScript story is here. Not yet. See bugger-daemon’s third-party docs. See also the endpoints implementation in Chromium. /json/protocol was added in Chrome 60. The endpoint is exposed as webSocketDebuggerUrl in /json/version. Note the browser in the URL, rather than page. If Chrome was launched with --remote-debugging-port=0 and chose an open port, the browser endpoint is written to both stderr and the DevToolsActivePort file in browser profile folder. Yes, as of Chrome 63! See Multi-client remote debugging support. Upon disconnnection, the outgoing client will receive a detached event. For example: View the enum of possible reasons. (For reference: the original patch). After disconnection, some apps have chosen to pause their state and offer a reconnect button.
Nucular is an immediate mode GUI library for Go, its implementation is a partial source port of Nuklear [0] by Micha Mettke. For a brief introduction to Immediate Mode GUI see [1] A window can be opened with the following three lines of code: The first line creates the MasterWindow object and sets its flags (usually 0 is fine) and updatefn as the update function. Updatefn will be responsible for drawing the contents of the window and handling the GUI logic (see the "Window Update and layout" section). The second line configures the theme, the font (passing nil will use the default font face) and the default scaling factor (see the "Scaling" section). The third line opens the window and starts its event loop, updatefn will be called whenever the window needs to be redrawn, this is usually only in response to mouse and keyboard events, if you want the window to be redrawn you can also manually call wnd.Update(). The update function is responsible for drawing the contents of the window as well as handling user events, this is usually done by calling methods of nucular.Window. For example, drawing a simple text button is done with this code: Widgets are laid out left to right and top to bottom, each row has a layout that can be configured calling the Layout* methods of nucular.Window. There are three main row layout modes: Static: in this mode the columns of the row have a fixed, user defined, width. This row layout can be selected calling Static or StaticScaled Dynamic: in this mode the columns of the row have a width proportional to the total width of the window. This row layout can be selected calling Dynamic, DynamicScaled or Ratio Space: in this mode widgets are positioned and sized arbitrarily. This row layout can be selected calling LayoutSpaceBegin or LayoutSpaceBeginRatio, once this row layout is selected widgets can be positioned using LayoutSpacePush or LayoutSpacePushRatio When calling SetStyle you can specify a scaling factor, this will be used to scale the sizes in the style argument and also all the size arguments for the Layout* functions. Links
Package tui is a library for building user interfaces for the terminal. Widgets are the main building blocks of any user interface. They allow us to present information and interact with our application. It receives keyboard and mouse events from the terminal and draws a representation of itself. Widgets are structured using layouts. Layouts are powerful tools that let you position your widgets without having to specify their exact coordinates. Here, the VBox will ensure that the Button will be placed underneath the Label. There are currently three layouts to choose from; VBox, HBox and Grid. Sizing of widgets is controlled by its SizePolicy. For now, you can read more about how size policies work in the Qt docs: http://doc.qt.io/qt-5/qsizepolicy.html#Policy-enum
Package oauth1 is a Go implementation of the OAuth1 spec RFC 5849. It allows end-users to authorize a client (consumer) to access protected resources on their behalf (e.g. login) and allows clients to make signed and authorized requests on behalf of a user (e.g. API calls). It takes design cues from golang.org/x/oauth2, providing an http.Client which handles request signing and authorization. Package oauth1 implements the OAuth1 authorization flow and provides an http.Client which can sign and authorize OAuth1 requests. To implement "Login with X", use the https://github.com/dghubble/gologin packages which provide login handlers for OAuth1 and OAuth2 providers. To call the Twitter, Digits, or Tumblr OAuth1 APIs, use the higher level Go API clients. * https://github.com/dghubble/go-twitter * https://github.com/dghubble/go-digits * https://github.com/benfb/go-tumblr Perform the OAuth 1 authorization flow to ask a user to grant an application access to his/her resources via an access token. 1. When a user performs an action (e.g. "Login with X" button calls "/login" route) get an OAuth1 request token (temporary credentials). 2. Obtain authorization from the user by redirecting them to the OAuth1 provider's authorization URL to grant the application access. Receive the callback from the OAuth1 provider in a handler. 3. Acquire the access token (token credentials) which can later be used to make requests on behalf of the user. Check the examples to see this authorization flow in action from the command line, with Twitter PIN-based login and Tumblr login. Use an access Token to make authorized requests on behalf of a user. Check the examples to see Twitter and Tumblr requests in action.
Package oauth1 is a Go implementation of the OAuth1 spec RFC 5849. It allows end-users to authorize a client (consumer) to access protected resources on their behalf (e.g. login) and allows clients to make signed and authorized requests on behalf of a user (e.g. API calls). It takes design cues from golang.org/x/oauth2, providing an http.Client which handles request signing and authorization. Package oauth1 implements the OAuth1 authorization flow and provides an http.Client which can sign and authorize OAuth1 requests. To implement "Login with X", use the https://github.com/dghubble/gologin packages which provide login handlers for OAuth1 and OAuth2 providers. To call the Twitter, Digits, or Tumblr OAuth1 APIs, use the higher level Go API clients. * https://github.com/dghubble/go-twitter * https://github.com/dghubble/go-digits * https://github.com/benfb/go-tumblr Perform the OAuth 1 authorization flow to ask a user to grant an application access to his/her resources via an access token. 1. When a user performs an action (e.g. "Login with X" button calls "/login" route) get an OAuth1 request token (temporary credentials). 2. Obtain authorization from the user by redirecting them to the OAuth1 provider's authorization URL to grant the application access. Receive the callback from the OAuth1 provider in a handler. 3. Acquire the access token (token credentials) which can later be used to make requests on behalf of the user. Check the examples to see this authorization flow in action from the command line, with Twitter PIN-based login and Tumblr login. Use an access Token to make authorized requests on behalf of a user. Check the examples to see Twitter and Tumblr requests in action.
Acmeeval evaluates commands from inside the current Acme window's tag. Usage: Acmeeval adds each command to the tag, executes the command as Acme would have with button 2, and then restores the original tag. In addition to commands passed as arguments, acmeeval also executes each line from stdin as a command. Use acmeeval to access the Acme interactive command language from external client programs.
Package gist is an unofficial toolkit for file uploads to GitHub gist. macOS (via Homebrew): Manual: Download the latest release for your platform (Darwin/macOS, Linux, Windows): https://github.com/TheTannerRyan/gist/releases/latest. Unpack the tar, and copy the binary to a directory that is in the PATH. Here is an example on macOS (Darwin): The /usr/local/bin directory will work with most variants of UNIX. For Windows, you will have to add the parent directory to the system path. To use gist, you need to create a Github personal access token. To create a token, go to https://github.com/settings/tokens. Click the "generate new token" button and enter any description. For the scope, just select "gist". Then click generate token. Once you have a token, you should set the "GIST_KEY" environment variable to the token value. If you do not want to use an environment variable, you will have to copy and paste the token each time you would like to upload content. Global usage: Upload usage (same for secret uploads): All of the commands have short and long versions: The flags also have short aliases: The interface behaves the way it looks: If single or multiple files are being provided, and there are no file name overrides, the original file names will be used. For stdin and the clipboard, if no name is provided, the file will be uploaded as gistfile1.txt. Copyright (c) 2019 Tanner Ryan. All rights reserved. Use of this source code is governed by a BSD-style license that can be found in the LICENSE file. Ato Araki's Go clipboard library is under a BSD 3-clause license. Jeremy Saenz's Go command line library is under a MIT license. Once again, all rights reserved.
Package readability is a Go package that find the main readable content from a HTML page. It works by removing clutter like buttons, ads, background images, script, etc. This package is based from Readability.js by Mozilla, and written line by line to make sure it looks and works as similar as possible. This way, hopefully all web page that can be parsed by Readability.js are parse-able by go-readability as well.
Package gmail allows you to send email messages using Google GMail. You need to register the app on the Google server and get the configuration file that will be used for authorization. When you first initialize the application in the console will display the URL you need to go and get the authorization code. This code must be entered in response to the application and execution will continue. This function must be performed once the authorization keys stored in files. 1. Use wizard <https://console.developers.google.com/start/api?id=gmail> to create or select a project in the Google Developers Console and automatically turn on the API. Click Continue, then Go to credentials. 2. On the Add credentials to your project page, click the Cancel button. 3. At the top of the page, select the OAuth consent screen tab. Select an Email address, enter a Product name if not already set, and click the Save button. 4. Select the Credentials tab, click the Create credentials button and select OAuth client ID. 5. Select the application type Other, enter the name "Gmail API", and click the Create button. 6. Click OK to dismiss the resulting dialog. 7. Click the Download JSON button to the right of the client ID. 8. Move this file to your working directory and rename it client_secret.json.
Package readability is a Go package that find the main readable content from a HTML page. It works by removing clutter like buttons, ads, background images, script, etc. This package is based from Readability.js by Mozilla, and written line by line to make sure it looks and works as similar as possible. This way, hopefully all web page that can be parsed by Readability.js are parse-able by go-readability as well.
Package oauth1 is a Go implementation of the OAuth1 spec RFC 5849. It allows end-users to authorize a client (consumer) to access protected resources on their behalf (e.g. login) and allows clients to make signed and authorized requests on behalf of a user (e.g. API calls). It takes design cues from golang.org/x/oauth2, providing an http.Client which handles request signing and authorization. Package oauth1 implements the OAuth1 authorization flow and provides an http.Client which can sign and authorize OAuth1 requests. To implement "Login with X", use the https://github.com/dghubble/gologin packages which provide login handlers for OAuth1 and OAuth2 providers. To call the Twitter, Digits, or Tumblr OAuth1 APIs, use the higher level Go API clients. * https://github.com/dghubble/go-twitter * https://github.com/dghubble/go-digits * https://github.com/benfb/go-tumblr Perform the OAuth 1 authorization flow to ask a user to grant an application access to his/her resources via an access token. 1. When a user performs an action (e.g. "Login with X" button calls "/login" route) get an OAuth1 request token (temporary credentials). 2. Obtain authorization from the user by redirecting them to the OAuth1 provider's authorization URL to grant the application access. Receive the callback from the OAuth1 provider in a handler. 3. Acquire the access token (token credentials) which can later be used to make requests on behalf of the user. Check the examples to see this authorization flow in action from the command line, with Twitter PIN-based login and Tumblr login. Use an access Token to make authorized requests on behalf of a user. Check the examples to see Twitter and Tumblr requests in action.
Package oauth1 is a Go implementation of the OAuth1 spec RFC 5849. It allows end-users to authorize a client (consumer) to access protected resources on their behalf (e.g. login) and allows clients to make signed and authorized requests on behalf of a user (e.g. API calls). It takes design cues from golang.org/x/oauth2, providing an http.Client which handles request signing and authorization. Package oauth1 implements the OAuth1 authorization flow and provides an http.Client which can sign and authorize OAuth1 requests. To implement "Login with X", use the https://github.com/dghubble/gologin packages which provide login handlers for OAuth1 and OAuth2 providers. To call the Twitter, Digits, or Tumblr OAuth1 APIs, use the higher level Go API clients. * https://github.com/dghubble/go-twitter * https://github.com/dghubble/go-digits * https://github.com/benfb/go-tumblr Perform the OAuth 1 authorization flow to ask a user to grant an application access to his/her resources via an access token. 1. When a user performs an action (e.g. "Login with X" button calls "/login" route) get an OAuth1 request token (temporary credentials). 2. Obtain authorization from the user by redirecting them to the OAuth1 provider's authorization URL to grant the application access. Receive the callback from the OAuth1 provider in a handler. 3. Acquire the access token (token credentials) which can later be used to make requests on behalf of the user. Check the examples to see this authorization flow in action from the command line, with Twitter PIN-based login and Tumblr login. Use an access Token to make authorized requests on behalf of a user. Check the examples to see Twitter and Tumblr requests in action.
Package oauth1 is a Go implementation of the OAuth1 spec RFC 5849. It allows end-users to authorize a client (consumer) to access protected resources on their behalf (e.g. login) and allows clients to make signed and authorized requests on behalf of a user (e.g. API calls). It takes design cues from golang.org/x/oauth2, providing an http.Client which handles request signing and authorization. Package oauth1 implements the OAuth1 authorization flow and provides an http.Client which can sign and authorize OAuth1 requests. To implement "Login with X", use the https://github.com/dghubble/gologin packages which provide login handlers for OAuth1 and OAuth2 providers. To call the Twitter, Digits, or Tumblr OAuth1 APIs, use the higher level Go API clients. * https://github.com/dghubble/go-twitter * https://github.com/dghubble/go-digits * https://github.com/benfb/go-tumblr Perform the OAuth 1 authorization flow to ask a user to grant an application access to his/her resources via an access token. 1. When a user performs an action (e.g. "Login with X" button calls "/login" route) get an OAuth1 request token (temporary credentials). 2. Obtain authorization from the user by redirecting them to the OAuth1 provider's authorization URL to grant the application access. Receive the callback from the OAuth1 provider in a handler. 3. Acquire the access token (token credentials) which can later be used to make requests on behalf of the user. Check the examples to see this authorization flow in action from the command line, with Twitter PIN-based login and Tumblr login. Use an access Token to make authorized requests on behalf of a user. Check the examples to see Twitter and Tumblr requests in action.
Package tui is a library for building user interfaces for the terminal. Widgets are the main building blocks of any user interface. They allow us to present information and interact with our application. It receives keyboard and mouse events from the terminal and draws a representation of itself. Widgets are structured using layouts. Layouts are powerful tools that let you position your widgets without having to specify their exact coordinates. Here, the VBox will ensure that the Button will be placed underneath the Label. There are currently three layouts to choose from; VBox, HBox and Grid. Sizing of widgets is controlled by its SizePolicy. For now, you can read more about how size policies work in the Qt docs: http://doc.qt.io/qt-5/qsizepolicy.html#Policy-enum
Package websocketproxy is a reverse proxy for WebSocket connections.
Package oauth1 is a Go implementation of the OAuth1 spec RFC 5849. It allows end-users to authorize a client (consumer) to access protected resources on their behalf (e.g. login) and allows clients to make signed and authorized requests on behalf of a user (e.g. API calls). It takes design cues from golang.org/x/oauth2, providing an http.Client which handles request signing and authorization. Package oauth1 implements the OAuth1 authorization flow and provides an http.Client which can sign and authorize OAuth1 requests. To implement "Login with X", use the https://github.com/dghubble/gologin packages which provide login handlers for OAuth1 and OAuth2 providers. To call the Twitter, Digits, or Tumblr OAuth1 APIs, use the higher level Go API clients. * https://github.com/dghubble/go-twitter * https://github.com/dghubble/go-digits * https://github.com/benfb/go-tumblr Perform the OAuth 1 authorization flow to ask a user to grant an application access to his/her resources via an access token. 1. When a user performs an action (e.g. "Login with X" button calls "/login" route) get an OAuth1 request token (temporary credentials). 2. Obtain authorization from the user by redirecting them to the OAuth1 provider's authorization URL to grant the application access. Receive the callback from the OAuth1 provider in a handler. 3. Acquire the access token (token credentials) which can later be used to make requests on behalf of the user. Check the examples to see this authorization flow in action from the command line, with Twitter PIN-based login and Tumblr login. Use an access Token to make authorized requests on behalf of a user. Check the examples to see Twitter and Tumblr requests in action.
Package oauth1 is a Go implementation of the OAuth1 spec RFC 5849. It allows end-users to authorize a client (consumer) to access protected resources on their behalf (e.g. login) and allows clients to make signed and authorized requests on behalf of a user (e.g. API calls). It takes design cues from golang.org/x/oauth2, providing an http.Client which handles request signing and authorization. Package oauth1 implements the OAuth1 authorization flow and provides an http.Client which can sign and authorize OAuth1 requests. To implement "Login with X", use the https://github.com/dghubble/gologin packages which provide login handlers for OAuth1 and OAuth2 providers. To call the Twitter, Digits, or Tumblr OAuth1 APIs, use the higher level Go API clients. * https://github.com/dghubble/go-twitter * https://github.com/dghubble/go-digits * https://github.com/benfb/go-tumblr Perform the OAuth 1 authorization flow to ask a user to grant an application access to his/her resources via an access token. 1. When a user performs an action (e.g. "Login with X" button calls "/login" route) get an OAuth1 request token (temporary credentials). 2. Obtain authorization from the user by redirecting them to the OAuth1 provider's authorization URL to grant the application access. Receive the callback from the OAuth1 provider in a handler. 3. Acquire the access token (token credentials) which can later be used to make requests on behalf of the user. Check the examples to see this authorization flow in action from the command line, with Twitter PIN-based login and Tumblr login. Use an access Token to make authorized requests on behalf of a user. Check the examples to see Twitter and Tumblr requests in action.