API Authentication Deep Dive: How Proxed Securely Verifies Your Requests

Authentication is the foundation of API security. Let's explore how Proxed's multi-layered authentication works and why we designed it this way.

#
Authentication Flow Overview

When your app makes a request to Proxed, several security checks happen in sequence:

Initial Identification: Your project is identified through a project ID in the URL path
Authentication Method Detection: We determine which auth method you're using
Key Verification: We validate your API key(s) using a split-key approach
Device Validation: For production requests, we verify the authenticity of the iOS device
Usage Checks: We ensure your account is in good standing and within usage limits

This process takes milliseconds but provides multiple layers of security.

#
Three Ways to Authenticate

We support multiple authentication methods to accommodate different use cases:

#
1. Bearer Token Authentication (Recommended)

This is our primary method, supporting both test keys and device tokens:

curl -X POST https://api.proxed.dev/v1/openai/your-project-id/chat/completions \
  -H "Authorization: Bearer your-partial-key.your-token" \
  -H "Content-Type: application/json" \
  -d '{...}'

With this method:

The partial API key is extracted from the first part of the Bearer token
The second part can be either a test key or a DeviceCheck token
You don't need to provide an additional x-ai-key header

Why we use this format: Many AI SDKs don't support custom headers like x-ai-key, but they do support setting the Authorization header. The combined format allows us to transmit both the partial API key and device token in a single standard header that works with virtually any HTTP client or SDK.

#
2. Test Key Authentication (Development)

This method is designed for testing during development:

curl -X POST https://api.proxed.dev/v1/openai/your-project-id/chat/completions \
  -H "x-proxed-test-key: your-test-key" \
  -H "x-ai-key: your-partial-key" \
  -H "Content-Type: application/json" \
  -d '{...}'

This method:

Requires Test Mode to be enabled for your project
Requires both your test key and partial API key
Bypasses device verification
Should only be used during development

#
3. Device Token Authentication (Legacy)

Our original method, which we maintain for backward compatibility:

curl -X POST https://api.proxed.dev/v1/openai/your-project-id/chat/completions \
  -H "x-device-token: your-device-token" \
  -H "x-ai-key: your-partial-key" \
  -H "Content-Type: application/json" \
  -d '{...}'

This method:

Requires separate headers for the device token and API key
Still performs full device verification
Will eventually be deprecated in favor of the Bearer method

#
Under the Hood: How It Works

Let's explore what happens when a request hits our API gateway:

#
Project Resolution

We extract your project ID from the URL path parameter (/v1/provider/{projectId}/endpoint). This allows us to look up your project configuration, including whether you're in test mode and if device verification is enabled.

Using the project ID in the URL path makes your requests more RESTful and explicit about which project context they're operating in.

#
Key Splitting Architecture

We never store complete API keys for third-party providers. Instead:

You retain a portion of the key (partial key)
We store the complementary portion securely
Both parts are needed to reconstruct the full key
The full key only exists momentarily during request processing

This approach ensures that even if our servers were compromised, attackers would only have access to partial keys, not complete ones.

SDK Compatibility: Our Bearer token method (Authorization: Bearer partialKey.token) enables the use of standard AI SDKs that don't support custom headers. This means you can use official libraries from providers like OpenAI or Anthropic with minimal configuration, while still maintaining our security model.

#
Device Verification with Apple's DeviceCheck

For production requests, we validate that the request comes from a legitimate iOS device:

Your app requests a DeviceCheck token from Apple
Your app includes this token in the request to our API
Our server validates this token with Apple's servers
We proceed only if Apple confirms the device is legitimate

This prevents unauthorized usage from non-iOS environments, scripts, or emulators.

#
Authentication in Your iOS App

Here's how to implement authentication in your iOS app:

import DeviceCheck

func makeAuthenticatedRequest() async throws {
    // 1. Generate a DeviceCheck token (for production)
    let deviceToken = try await getDeviceToken()

    // 2. Prepare the API request with projectId in the path
    let projectId = "your-project-id" // UUID format: e29c1826-f314-4c9c-801f-0ce1827c8153
    var request = URLRequest(url: URL(string: "https://api.proxed.dev/v1/openai/\(projectId)/chat/completions")!)
    request.httpMethod = "POST"
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")

    // 3. Set authentication headers (Bearer token method)
    request.setValue("Bearer \(partialKey).\(deviceToken)", forHTTPHeaderField: "Authorization")

    // 4. Set request body and send
    request.httpBody = try JSONEncoder().encode(requestBody)
    let (data, response) = try await URLSession.shared.data(for: request)

    // 5. Process response
    // ...
}

func getDeviceToken() async throws -> String {
    guard DCDevice.current.isSupported else {
        throw AuthError.deviceCheckNotSupported
    }

    return try await withCheckedThrowingContinuation { continuation in
        DCDevice.current.generateToken { token, error in
            if let error = error {
                continuation.resume(throwing: error)
                return
            }

            guard let token = token else {
                continuation.resume(throwing: AuthError.tokenGenerationFailed)
                return
            }

            continuation.resume(returning: token.base64EncodedString())
        }
    }
}

#
Security Considerations

Our authentication system addresses several key security concerns:

API Key Protection
- Keys are never completely stored in any one location
- Keys are never embedded in client apps
- The full key is only momentarily reconstructed during request processing
Request Forgery Prevention
- DeviceCheck verification prevents requests from non-iOS sources
- Multiple authentication factors (project ID, API key, device token)
- Token-based approach that can be revoked if needed
Usage Control
- Rate limiting and usage tracking
- Project-specific permissions and settings
- Automatic detection of suspicious usage patterns

#
Best Practices

To maximize security in your application:

Use Bearer Authentication: Our recommended method for all new implementations
Rotate Keys Regularly: Create new API keys periodically
Keep Test Mode Disabled in production environments
Implement Proper Error Handling for authentication failures
Monitor Your Usage to detect unauthorized access attempts
Use HTTPS for all API communications
Include Project ID in URL Path: Always use the project ID in the URL path for better REST practices

#
What's Next

Authentication is just one part of our security architecture. In upcoming posts, we'll explore:

Advanced rate limiting strategies
Custom validation rules for API requests
Enterprise security features
Multi-environment key management

By understanding and properly implementing these authentication methods, you're building a strong foundation for your AI-powered applications.

API Authentication Deep Dive: How Proxed Securely Verifies Your Requests

#Authentication Flow Overview

#Three Ways to Authenticate

#1. Bearer Token Authentication (Recommended)

#2. Test Key Authentication (Development)

#3. Device Token Authentication (Legacy)

#Under the Hood: How It Works

#Project Resolution

#Key Splitting Architecture

#Device Verification with Apple's DeviceCheck

#Authentication in Your iOS App

#Security Considerations

#Best Practices

#What's Next