Rev.io API Authentication

This documentation covers how to programmatically exchange an API key for a JWT token and use it to make authenticated requests to Rev.io APIs using curl commands. In order to get a key, a system administrator will need to create a key via Admin > API Management. Role-based access controls are based on the key's creator and apply to the API user. This may limit/change the valid activities that can be performed.

Authentication Flow

Step 1: Exchange API Key for JWT Token

Use your Rev.io API key to obtain a JWT token:

curl -X POST https://api.psarev.io/api/v1/auth/api-key/exchange \
  -H "Content-Type: application/json" \
  -d '{"apiKey": "your-api-key-here"}'

Expected Response:

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Step 2: Extract JWT Token

From the response, extract the JWT token from the data.token field. You can use tools like jq to parse the JSON:

TOKEN=$(curl -s -X POST https://api.psarev.io/api/v1/auth/api-key/exchange \
  -H "Content-Type: application/json" \
  -d '{"apiKey": "your-api-key-here"}' | jq -r '.data.token')

Step 3: Use Authorization and X-Revio-Host Headers for API Requests

Include the JWT token in the Authorization header as a Bearer token and an X-Revio-Host header for all subsequent API calls. The value for the X-Revio-Host header will be the domain of your PSA website:

curl -X GET https://api.psarev.io/billing/api/v1/contacts \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Revio-Host: acme.psarev.io" \
  -H "Content-Type: application/json"

API Endpoints Examples

Here are a few of the available endpoints and example curl commands:

Get Contacts

curl -X GET https://api.psarev.io/billing/api/v1/contacts \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Revio-Host: acme.psarev.io"

Get Specific Contact

curl -X GET https://api.psarev.io/billing/api/v1/contacts/{id} \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Revio-Host: acme.psarev.io"

Get Customers

curl -X GET https://api.psarev.io/billing/api/v1/customers \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Revio-Host: acme.psarev.io"

Get Specific Customer

curl -X GET https://api.psarev.io/billing/api/v1/customers/{customerId} \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Revio-Host: acme.psarev.io"

Complete Script Example

Here's a complete bash script that demonstrates the full workflow:

#!/bin/bash

# Set your API key
API_KEY="your-api-key-here"
BASE_URL="https://api.psarev.io"
REVIO_HOST="acme.psarev.io"

# Step 1: Exchange API key for JWT token
echo "Exchanging API key for JWT token..."
RESPONSE=$(curl -s -X POST "$BASE_URL/api/v1/auth/api-key/exchange" \
  -H "Content-Type: application/json" \
  -d "{\"apiKey\": \"$API_KEY\"}")

# Step 2: Extract token from response
TOKEN=$(echo "$RESPONSE" | jq -r '.data.token')

if [ "$TOKEN" = "null" ] || [ -z "$TOKEN" ]; then
  echo "Error: Failed to get token"
  echo "Response: $RESPONSE"
  exit 1
fi

echo "Successfully obtained JWT token"

# Step 3: Use token to make API requests
echo "Making API request to get contacts..."
curl -X GET "$BASE_URL/billing/api/v1/contacts" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Revio-Host: $REVIO_HOST" \
  -H "Content-Type: application/json"

Error Handling

Invalid API Key

If the API key is invalid, you'll receive an HTTP 4xx error:

curl -X POST https://api.psarev.io/api/v1/auth/api-key/exchange \
  -H "Content-Type: application/json" \
  -d '{"apiKey": "invalid-key"}' \
  -w "\nHTTP Status: %{http_code}\n"

Token Expiration

JWT tokens may expire. If you receive a 401 Unauthorized error, re-exchange your API key for a new token:

# Check if request fails with 401
HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  -X GET https://api.psarev.io/billing/api/v1/contacts \
  -H "Authorization: Bearer $TOKEN")

if [ "$HTTP_STATUS" = "401" ]; then
  echo "Token expired, re-exchanging..."
  # Re-run token exchange process
fi

Security Best Practices

1. Store API keys securely: Use environment variables or secure credential storage
2. Token rotation: Regularly exchange for new tokens
3. HTTPS only: Always use HTTPS for API requests
4. Don't log tokens: Avoid logging JWT tokens in plain text

# Secure way to handle API key
read -s -p "Enter API key: " API_KEY
echo
# Proceed with token exchange...

This approach allows you to integrate Rev.io APIs into any system or script that can make HTTP requests, without requiring the developer portal UI.