Authentication

The Visiwise API uses API Keys to authenticate requests. You must include your unique API Key in every request to identify your account.

Treat your API Key like a password

Your API Key grants access to your Visiwise data. You must keep it secure and never share it or expose it in publicly accessible areas like client-side code or public repositories.

Obtaining Your API Key

To request an API Key, contact sales. Our team will review your request and grant access in less than one business day.

Making Authenticated Requests

To authenticate a request, you need to provide your API Key in the Authorization header using the Bearer authentication scheme.

Replace YOUR_VISIWISE_API_KEY in the examples below with your key.

cURL Example

Here is how you can make an authenticated request to list shipments using cURL.

curl -X GET "https://www.visiwise.co/api/v1/shipments/" \
  -H "Authorization: Bearer YOUR_VISIWISE_API_KEY"

Python Example

This example shows you how to make the same request using Python's popular requests library.

import requests
import os

# We recommend storing your API key in an environment variable
# for security.
api_key = os.environ.get("VISIWISE_API_KEY", "YOUR_VISIWISE_API_KEY")

url = "https://www.visiwise.co/api/v1/shipments"

headers = {
  "Authorization": f"Bearer {api_key}",
  "Content-Type": "application/json"
}

response = requests.get(url, headers=headers)

if response.status_code == 200:
  print("Success:")
  print(response.json())
else:
  print(f"Error: {response.status_code}")
  print(response.json())

Regenerating Your API Key

If your API Key is ever compromised, please contact our support team to regenerate a new one. This action will immediately and permanently invalidate your old key.

1. Send an email to [email protected] requesting API key regeneration.
2. Our support team will review your request and securely send you a new API key.

Handling Authentication Errors

If a request has an invalid or missing API Key, the API will respond with a 401 Unauthorized or 403 Forbidden HTTP status code. The response body will contain a JSON object with a specific error code that helps you diagnose the issue.

You can use these error codes to build robust integrations that handle authentication failures gracefully.

HTTP Status Code	Error Code (in detail)	Description
401 Unauthorized	INVALID_API_KEY	The API Key you provided is missing, invalid, expired, or has been revoked.
403 Forbidden	INVALID_USER	Your API Key is valid, but it does not have the necessary permissions for this action.

Example Error Response

All error responses from the API follow this standard structure.

{
  "error": {
    "code": "authentication_error",
    "message": "Authentication error",
    "details": [
      {
        "code": "INVALID_API_KEY",
        "target": "api_key",
        "message": "Invalid API key.",
        "suggested_fix": "Please provide a valid API key."
      }
    ]
  },
  "data": null
}