Authentication

Authentication calls are how users gain access to vaults through the API.

Every Vault API endpoint requires an Vault Authentication Token called a Session ID. This can be acquired by following the steps described in this article. Vault's authentication response contains a Session ID and a list of all vaults in the domain to which the API user has been given access. Once successfully authenticated with a vault, all subsequent API requests must contain the Authorization HTTP header with the Session ID received as part of the authentication call.

Vault supports the following API authentication methods:

Note: You must have a Vault permission set which allows API access.

Learn about Authentication & Vault Security in Vault Help.

Username & Password Authentication

Request

Send POST to https://{customer}/api/{version}/auth.

Headers

Input Content-Type - Name-Value Pair application/x-www-form-urlencoded
Response Accept - JSON application/json (default) or XML application/xml

Parameters

{customer} - The URL of the vault to which you want to authenticate (e.g., https://promomats-veevapharm.veevavault.com).
{version} - The version of the API with which you want to authenticate (e.g., v10.0, v11.0, v12.0, etc.).

Input

username - The Vault username used to log into your vault (e.g., quinn@veevapharm.com).
password - The Vault password used to log into your vault (e.g., ABC123).

Example

$ curl -X POST https://promomats-veevapharm.veevavault.com/api/v13.0/auth \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Accept: application/xml" \ 
-d "username=quinn@veevapharm.com&password=ABC123"

In this example:

  • We're authenticating with the PromoMats vault (promomats-veevapharm.veevavault.com) in our domain. The API version is set to v13.0.
  • We've set the input format to application/x-www-form-urlencoded, allowing us to enter the username and password as name-value pairs.
  • We're requesting an XML response. This is optional. If this were not specified, Vault would return a JSON response by default.
  • We've entered the username and password.

Response

{
  "responseStatus": "SUCCESS",
  "sessionId": "3B3C45FD240E26F0C3DB4F82BBB0C15C7EFE4B29EF9916AF41AF7E44B170BAA01F232B462BE5C2BE2ACB82F6704FDA216EBDD69996EB23A6050723D1EFE6FA2B",
  "userId": 12021,
  "vaultIds": [
    {
      "id": 1776,
      "name": "PromoMats",
      "url": "https://promomats-veevapharm.veevavault.com/api"
    },
    {
      "id": 1777,
      "name": "eTMF",
      "url": "https://etmf-veevapharm.veevavault.com/api"
    },
    {
      "id": 1778,
      "name": "MedComms",
      "url": "https://medcomms-veevapharm.veevavault.com/api"
    },
    {
      "id": 1779,
      "name": "QualityDocs",
      "url": "https://qualitydocs-veevapharm.veevavault.com/api"
    },
    {
      "id": 1780,
      "name": "Submissions",
      "url": "https://submissions-veevapharm.veevavault.com/api"
    },
    {
      "id": 1781,
      "name": "RIM Submissions",
      "url": "https://rimsubmissions-veevapharm.veevavault.com/api"
    }
    {
      "id": 1782,
      "name": "Platform",
      "url": "https://platform-veevapharm.veevavault.com/api"
    }
  ],
  "vaultId": 1776
}

Details

On SUCCESS, the response header includes the following information:

  • sessionId - The Session ID is an Authentication Token which must be submitted with all subsequent API requests. This can be cached and reused until the token expires.
  • userId - The system-managed id value of the user who initiated the authentication request.

The vaultIds portion of the response shows all vaults in your domain to which you have been assigned access. The following information is included for each vault:

  • id - The numeric id value of each vault. The Vault ID is displayed in Admin > Settings > General Settings.
  • name - The name of each vault. The Vault Name is displayed in Admin > Settings > General Settings.
  • url - The URL of each vault. To access information in the vault, add the appropriate Vault API endpoint to this URL.

A separate portion of the response lists the vaultId of the vault to which the Authentication Token applies. For example:

  • In the response above, we've successfully authenticated with "vaultId": 1776, which is a PromoMats vault in our domain.
  • We can only use this Session ID to submit API requests to this vault. To access a different vault, we must submit a new authentication request to its URL.

Authentication Token

To access information in your vault, use the URL provided in the url parameter as the base for all subsequent endpoints.

The Session ID must be included on all requests to Vault API inside the HTTP Request Header Authorization. For example:

$ curl -X GET -H "Authorization: 3B3C45FD240E26F0C3DB4F82BBB0C15C7EFE4B29EF9916AF41AF7E44B170BAA01F232B462BE5C2BE2ACB82F6704FDA216EBDD69996EB23A6050723D1EFE6FA2B" 
https://promomats-veevapharm.veevavault.com/api/v13.0/objects/documents

Alternatively, you may include the Session ID in the request parameter auth. For example:

$ curl -X GET https://promomats-veevapharm.veevavault.com/api/v13.0/objects/documents?auth=3B3C45FD240E26F0C3DB4F82BBB0C15C7EFE4B29EF9916AF41AF7E44B170BAA01F232B462BE5C2BE2ACB82F6704FDA216EBDD69996EB23A6050723D1EFE6FA2B

Note: The auth request parameter (if present) will overwrite the Authorization HTTP Header value.

Session Timeout

Your Vault Authentication Token will expire after a certain period of idle time. When this occurs, you will receive the following error on the next API call.

{
    "responseStatus": "FAILURE",
    "errors": [
        {
            "type": "INVALID_SESSION_ID",
            "message": "Authentication failed for session id: 3B3C45FD240E26F0C3DB4F82BBB0C15C7EFE4B29EF9916AF41AF7E44B170BAA01F232B462BE5C2BE2ACB82F6704FDA216EBDD69996EB23A6050723D1EFE6FA2B."
        }
    ]
}

Contact your Vault Administrator to determine the session duration for your vault.

Errors

Error Type Error Message Description
USERNAME_OR_PASSWORD_INCORRECT Invalid login credentials provided. You have entered an invalid username and/or password.
USER_LOCKED_OUT Account locked out due to repeated failed login requests. Contact your Vault Admin.
INSUFFICIENT_ACCESS Insufficient privileges to perform the action. You must be assigned a permission set which allows access to the API.
METHOD_NOT_SUPPORTED Requested method [{METHOD}] not supported. Use the HTTP POST method.

History

Since v1

Top

Single Sign-On (SSO) Authentication

API users authenticated with a SAML Identity Provider (IdP) can access Vault without having to provide a username and password. Learn about Configuring Single Sign-On in Vault Help.

The "Vault SSO Login URL" endpoint supports POST requests containing the encoded SAML Response issued by your IdP, verifies that the SAML Response is valid and not expired, and returns a standard Vault Authentication Response.

Parameters

SAMLResponse - The encoded SAMLResponse as returned by the IdP.
vaultDNS - The DNS name (hostname) for the vault to which the user will be logged in.

If the SAMLResponse is valid but the value in vaultDNS parameter is blank, invalid, or is not one of the vaults to which the user has access, a session for the "default vault" in the domain will be created. The default vault is the one the user logged into last. If the user has never logged into any vaults in the domain, they will be logged into first vault in the domain to which they have access.

Response

The response is the same as the Username & Password Authentication response described above.

Errors

Error Type Error Message
PARAMETER_REQUIRED The SAMLResponse object was expected, but none was provided.
INVALID_SESSION_ID The SAMLResponse didn't validate with IdP.
INVALID_DATA An invalid value was specified for the parameter [SAMLResponse].
INVALID_DATA The SAMLResponse has expired.

History

Since v11

Top

Salesforce Delegated Authentication

This allows Salesforce.com users to access Vault resources via the API without having to separately authenticate to Vault. Learn about Salesforce Delegated Authentication in Vault Help.

The following prerequisites apply:

  • A valid Vault user must exist with a Security Policy enabled for Salesforce.com Delegated Authentication.
  • The trusted 18-character Salesforce.com Org ID must be provided.
  • A user with matching username must exist in Salesforce.com Org ID.

Headers

When a user on Salesforce.com tries to access a Vault resource, Salesforce.com issues a direct API call to Vault passing the following three HTTP Headers or query string parameters:

HTTP Header Query Parameter Description
Authorization auth Set to a valid Salesforce.com session token.
X-Auth-Host ext_url Set to a Salesforce.com URL which Vault can use to validate the Salesforce.com session token.
X-Auth-Provider ext_ns Set to sfdc specifying Salesforce.com auth delegation.

Example

$ curl –k -d "q=SELECT id, name__v, type__v FROM documents" \
-H "Authorization: 9B31A9EC08031CD17022BC858BA73BFC6BAFE0F7EC212986CA05AC4E66FD4AFCC8E7164FD4B14" \
-H "X-Auth-Host: https://veevapharm.salesforce.com" \
-H "X-Auth-Provider: sfdc" \
https://promomats-veevapharm.veevavault.com/api/v13.0/query

Example

$ curl –k -d "q=SELECT id, name__v, type__v FROM documents" \
https://promomats-veevapharm.veevavault.com/api/v13.0/query

Note: The query string parameters (if present) will overwrite the corresponding HTTP Header values.

Example

$ curl –k -d "q=SELECT id, name__v, type__v FROM documents" \
-H "Authorization: {SFDC_SESSION_TOKEN}" \
-H "X-Auth-Provider: sfdc" \
-H "X-Auth-Host: https://mysf.salesforce.com" \
https://promomats-veevapharm.veevavault.com/api/v13.0/query

Upon receipt of the request, Vault will:

  • Validate the Salesforce.com token with Salesforce.com.
  • Verify that the Salesforce.com user exists in the vault.
  • Validate that the user has access to the resource.
  • Respond to the request with either successful JSON/XML response or failure

Errors

Error Type Error Message Description
INSUFFICIENT_ACCESS User doesn't have sufficient privileges to perform the action on the Vault resource. This can happen if the Salesforce.com session is invalid, the Salesforce.com user is not found in Vault, or the Vault user hasn't been assigned privileges to access the vault or API.

History

Since v5

Top