HTTP API Overview
The VisualVault HTTP APIs use HTTP verbs (GET,PUT,POST,DELETE) to request, update, create, and delete data using the HTTP protocol for communication. This type of API architecture is also referred to as a "restful" or representational state transfer (REST) API style. Each VisualVault resource (user,form,document,etc) has a unique URI and an HTTP request's verb type determines what action is performed.
VisualVault HTTP APIs use the OAuth 2.0 protocol for authentication and authorization. VisualVault supports OAuth 2.0 grant types (security flows) for web server, installed, and client-side applications.
The OAuth 2.0 authorization protocol enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf.
The steps below are for direct HTTP API access. The API client libraries implement the steps below and require only an API Key / API Secret to get started. You should read the Authentication and authorization overview topic even when using the API client libraries to gain an understanding of the appropriate security flow for your specific use case.
1 - Log in and obtain an API Key/Secret
- VisualVault admin account. Accounts that are members of an administrative group (VaultAccess or VaultAdmins groups) may be issued an API Key/Secret. This is the appropriate option to choose for developer testing or for "Service Accounts" which will need to access resources using the identity of the admin account.
- Registered Application. Registering an application is the preferred way to obtain an API Key/Secret. Applications access resources on behalf of a resource owner (a user account). When an application wants to use the API to access resources or actions, the application must first obtain permission from the resource owner. This type of resource authorization is called an authorization grant and may be performed without the application knowing the resource owner's credentials (user id/password).
2 - Obtain an access token from the Authorization Server
Before your application can access private data using the VisualVault REST APIs, the application must authenticate and obtain an access token. An access token grants access to APIs beloging to a specific scope. The scope you provide when requesting an access token determines the set of resources and operations the access token permits. A single access token can grant access to multiple APIs associated with the same scope.
Each REST API is a specific URL representing either a 'resource' or an 'operation'. Each API resource/operation request requires an access token be included in the HTTP Authorization header.
Read the Access Token topic for an example of requesting an access token.
3 - Send the access token to an API
After an application obtains an access token, it sends the token to a VisualVault API in an HTTP "authorization" header.
Access tokens are valid only for the set of operations and resources requested in the scope of the access token request. For example, if an access token is issued for a VisualVault customer database, it does not grant access to the VisualVault Administration API or other customer database APIs. You can, however, send that access token to multiple APIs within the same scope multiple times until the access token expires.
4 - Refresh the access token if necessary
Access tokens have limited lifetimes defined by an expiration date returned with the access token. If your application needs API access beyond the lifetime of an access token, a refresh token may be used to obtain a new access token. Depending upon the OAuth grant type in use, when you request an access token a refresh token is also included in the HTTP response. Refresh tokens have a longer lifetime than access tokens and allow you to request a new access token without providing your application's credentials or the resource owner's (account using your application) credentials a second time.