Using Your API Key

Using Your API Key #

Now that you have an API key, learn how to use it securely in your applications.

Basic Usage #

Include your API key in the Authorization header of every request:

Authorization: Bearer agl_sk_your_key_here

Implementation by Language #

JavaScript (Node.js) #

const axios = require('axios');

const API_KEY = process.env.VOXPRIA_API_KEY;
const BASE_URL = 'https://app.voxpria.com/api/v1';

async function makeRequest() {
  const response = await axios.get(`${BASE_URL}/credits`, {
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    }
  });
  return response.data;
}

Python #

import os
import requests

API_KEY = os.getenv('VOXPRIA_API_KEY')
BASE_URL = 'https://app.voxpria.com/api/v1'

def make_request():
    response = requests.get(
        f'{BASE_URL}/credits',
        headers={
            'Authorization': f'Bearer {API_KEY}',
            'Content-Type': 'application/json'
        }
    )
    return response.json()

PHP #

$apiKey = getenv('VOXPRIA_API_KEY');
$baseUrl = 'https://app.voxpria.com/api/v1';

$ch = curl_init("$baseUrl/credits");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer $apiKey",
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);

C# #

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;

var apiKey = Environment.GetEnvironmentVariable("VOXPRIA_API_KEY");
var baseUrl = "https://app.voxpria.com/api/v1";

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = 
    new AuthenticationHeaderValue("Bearer", apiKey);

var response = await client.GetAsync($"{baseUrl}/credits");
var content = await response.Content.ReadAsStringAsync();

Production Checklist #

Error Handling #

Always handle API errors gracefully:

try {
  const response = await makeApiCall();
  // Handle success
} catch (error) {
  if (error.response) {
    switch (error.response.status) {
      case 401:
        // Unauthorized - check API key
        break;
      case 403:
        // Forbidden - check scopes
        break;
      case 429:
        // Rate limited - implement backoff
        break;
      case 500:
        // Server error - retry with backoff
        break;
    }
  }
}

Rate Limit Handling #

Implement exponential backoff when rate limited:

async function retryWithBackoff(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.response?.status === 429) {
        const delay = Math.pow(2, i) * 1000;
        await new Promise(resolve => setTimeout(resolve, delay));
      } else {
        throw error;
      }
    }
  }
}

Monitoring Usage #

Track your API key usage:

• Monitor request counts
• Watch for unusual patterns
• Set up alerts for high usage
• Review access logs regularly
• Check credit consumption

Key Rotation #

Rotate keys every 90 days:

1. Create new key with same scopes
2. Deploy new key to staging
3. Test thoroughly
4. Deploy to production
5. Monitor for 24-48 hours
6. Revoke old key