Skip to content

Authentication

For data security, the VectorSurv API utilizes Bearer Authentication. Each request to the VectorSurv API requires a valid token associated with a VectorSurv agency or user.

Bearer authentication

Bearer authentication is an authentication scheme that involves including a bearer token in the request header to authenticate and authorize access to protected resources. The bearer token is obtained through a separate authentication process and is then included in subsequent API requests. Learn more about Bearer authentication.

Obtaining a token

You can use Bearer authentication to authenticate your requests against the VectorSurv API. Tokens generated in this way expire after one hour. With a username and password for the VectorSurv Gateway, the API's /login endpoint can provide you with a token. Tokens are linked to the login that created them - a token generated by an agency manager has a higher level of permission than a token generated by a non-manager user.

Requirements

VectorSurv username and password

Obtaining a token sample code

auth_request.js
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
const axios = require("axios");

async function getAuthToken() {
  const url = "https://api.vectorsurv.org/login";
  const username = "your_gateway_username";
  const password = "your_gateway_password";

  try {
    const response = await axios.post(url, {
      params: {
        username,
        password,
      },
    });

    const your_auth_token = response.data.token;

    return your_auth_token;
  } catch (error) {
    console.error("Error:", error.message);
  }
}

// Use this token as needed
const your_auth_token =  await getAuthToken();
auth_request.r
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
library(httr)
library(jsonlite)

getAuthToken <- function() {
  headers <- c(
    'Content-Type' = 'application/json'
  )

  url <- "https://api.vectorsurv.org/login"

  body <- list(
    username = your_gateway_username,
    password = your_gateway_password
  )

  tryCatch({
    # Make the API request
    response <- POST(url, body = jsonlite::toJSON(body, auto_unbox = TRUE), add_headers(headers))

    # Check the response status code and category
    status_code <- http_status(response)$status_code
    status_category <- http_status(response)$category

    # Check the status code of the response
    if (status_category == "Success") {
      # Response status is successful (e.g., status code 200)
      response_content <- httr::content(response, 'parsed')
      # Use this token as needed
      your_auth_token <- response_content$token
      return(your_auth_token)
    } else {
      # Response status is not successful (e.g., status code 422)
      response_content <- httr::content(response, 'text')
      message("Error response content:", response_content)
    }
  }, error = function(e) {
    # Any other exceptions that might occur during the API request
    message("An error occurred during the API request. Error message:", e$message)
  })
}

# Use this token as needed
your_auth_token = getAuthToken()
auth_request.sh
cURL --location --request POST 'https://api.vectorsurv.org/login?username=your_gateway_username&password=your_gateway_password'

Note that you must replace your_gateway_username and your_gateway_password with your gateway login credentials

Using a Bearer Token

Include your token in the headers of all requests you make. For instance, to request a list of sites:

Using a Bearer Token sample code

authorized_request.js
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
async function getSiteListWithAuthentication() {
  const url = "https://api.vectorsurv.org/v1/site";
  const token = "your_auth_token";

  try {
    const response = await axios.get(url, {
      headers: {
        Authorization: `Bearer ${token}`,
      },
    });

    // Handle the response data
    yourDataHandler(response.data);
  } catch (error) {
    // Handle any errors
    console.error("Error:", error.message);
  }
}

getSiteListWithAuthentication();
authorized_request.r
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
library(httr)
library(jsonlite)

makeAuthorizedSiteRequest <- function(token) {
  headers = c(
    Authorization = paste("Bearer", token),
    "Content-Type" = "application/json"
  )

  url <- "https://api.vectorsurv.org/v1/site"

  tryCatch({
    # Make the API request
    response <- GET(url, add_headers(headers))

    # Check the response status code and category
    status_code <- http_status(response)$status_code
    status_category <- http_status(response)$category

    # Check the status code of the response
    if (status_category == "Success") {
      # Response status is successful (e.g., status code 200)
      content <- httr::content(response, "text")
      # Use this data frame as needed
      content_df = fromJSON(content)
    } else {
      # Response status is not successful (e.g., status code 422)
      response_content <- httr::content(response, 'text')
      message("Error response content:", response_content)
    }
  }, error = function(e) {
    # Any other exceptions that might occur during the API request
    message("An error occurred during the API request. Error message:", e$message)
  })
}

makeAuthorizedSiteRequest(your_auth_token)

curl --location 'https://api.vectorsurv.org/v1/site/' \
-H "Authorization: Bearer your_auth_token" \
-H "Content-Type: application/json"

Note that you must replace your_auth_token with your actual token.

Agency Token

Any VectorSurv agency can generate a token ("Agency Token"). Agency Tokens were developed as the authentication method for the VectorSurv Web Services and continue to work as authentication for the API. Agency Tokens are typically generated by agency managers in the VectorSurv Gateway. For more information about generating an Agency Token, visit our Agency Tokens Gateway documentation.

To authenticate with an agency token, the token must be included in the headers of all requests you make. For instance, to request a list of sites:

Using an Agency Token sample code

JavaScript example
authorized_request.js
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
async function getSiteListWithAuthentication() {
  const url = "https://api.vectorsurv.org/v1/site";
  const token = "your_agency_token";

  try {
    const response = await axios.get(url, {
      headers: {
        Authorization: `Bearer ${token}`,
      },
    });

    // Handle the response data
    yourDataHandler(response.data);
  } catch (error) {
    // Handle any errors
    console.error("Error:", error.message);
  }
}

getSiteListWithAuthentication();
authorized_request.r
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
library(httr)
library(jsonlite)

makeAuthorizedSiteRequest <- function(token) {
  headers = c(
    Authorization = paste("Bearer", token),
    "Content-Type" = "application/json"
  )

  url <- "https://api.vectorsurv.org/v1/site"

  tryCatch({
    # Make the API request
    response <- GET(url, add_headers(headers))

    # Check the response status code and category
    status_code <- http_status(response)$status_code
    status_category <- http_status(response)$category

    # Check the status code of the response
    if (status_category == "Success") {
      # Response status is successful (e.g., status code 200)
      content <- httr::content(response, "text")
      # Use this data frame as needed
      content_df = fromJSON(content)
    } else {
      # Response status is not successful (e.g., status code 422)
      response_content <- httr::content(response, 'text')
      message("Error response content:", response_content)
    }
  }, error = function(e) {
    # Any other exceptions that might occur during the API request
    message("An error occurred during the API request. Error message:", e$message)
  })
}

makeAuthorizedSiteRequest(your_agency_token)

curl --location 'https://api.vectorsurv.org/v1/site/' \
-H "Authorization: Bearer your_agency_token" \
-H "Content-Type: application/json"

Note that you must replace your_agency_token with your actual agency token.

Additional Information

Sharing your credentials

The authentication token and password provide access to your data, and should be protected. Never share your credentials or save them somewhere that may be shared, such as on GitHub or in client-side code.

Environment Variables

Environment variables are variables whose value is set outside the program. Using environment variables to set authentication credentials helps to ensure the security of your VectorSurv account by keeping them private. Learn more about using environment variables in R and using environment variables in Node.js.

HTTPS vs HTTP

Successful API requests use HTTPS and require authentication. Calls using plain HTTP or omitting authentication will fail.