Authentication

Authenticate requests to the FlexPrice API

The FlexPrice API uses API key authentication to secure requests. All API endpoints (except public webhooks) require a valid API key.

API Key Authentication

API keys are passed in the X-API-Key header with each request:

Authenticated Request

curl -X GET http://localhost:8080/v1/customers \
  -H "X-API-Key: 0cc505d7b917e0b1f25ccbea029dd43f4002edfea46b7f941f281911246768fe"

The X-API-Key header is required for all authenticated endpoints. Requests without a valid API key will receive a 401 Unauthorized response.

How API Keys Work

Key Structure

FlexPrice API keys are:

• 64-character hexadecimal strings (32 bytes encoded as hex)
• Generated using cryptographically secure random number generation
• Stored as SHA-256 hashes in the system for security

X-API-Key · string · required

Your FlexPrice API key. This is a 64-character hexadecimal string that authenticates your requests.

Key Validation

When you make a request:

1. The API extracts the key from the X-API-Key header
2. The key is hashed using SHA-256
3. The hash is looked up in the configuration
4. If found and active, the request is authenticated with the associated tenant and user context

Getting Your API Key

Development Environment

For local development, a default API key is provided in the setup:

Default Development Key

0cc505d7b917e0b1f25ccbea029dd43f4002edfea46b7f941f281911246768fe

This key is for development only. Never use it in production environments.

Creating API Keys

You can create API keys through the FlexPrice dashboard or API:

Create API Key

curl -X POST http://localhost:8080/v1/secrets/api/keys \
  -H "X-API-Key: your-existing-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API Key",
    "description": "Key for production integrations"
  }'

The full API key is only shown once during creation. Store it securely - you won’t be able to retrieve it again.

Managing API Keys

List API Keys

Retrieve all API keys for your account:

List Keys

curl -X GET http://localhost:8080/v1/secrets/api/keys \
  -H "X-API-Key: your-api-key"

Delete API Keys

Revoke an API key immediately:

Delete Key

curl -X DELETE http://localhost:8080/v1/secrets/api/keys/key_abc123 \
  -H "X-API-Key: your-api-key"

Deleting an API key immediately revokes access. Any applications using that key will receive 401 Unauthorized errors.

Environment Context

API keys are associated with a specific tenant and environment. After authentication, the API automatically scopes all operations to the correct environment context.

You can create separate API keys for production and development environments to maintain isolation and security.

Authentication Errors

The API returns specific errors for authentication issues:

Missing API Key

Status Code: 401 Unauthorized

{
  "success": false,
  "error": {
    "message": "API key required",
    "internal_error": "permission_denied"
  }
}

Invalid API Key

Status Code: 401 Unauthorized

{
  "success": false,
  "error": {
    "message": "Invalid API key",
    "internal_error": "permission_denied"
  }
}

Inactive API Key

Status Code: 403 Forbidden

{
  "success": false,
  "error": {
    "message": "API key is inactive",
    "internal_error": "permission_denied"
  }
}

Best Practices

Security

1. Never commit API keys

   Keep API keys out of version control. Use environment variables or secrets management systems.

   .env file

   FLEXPRICE_API_KEY=your-api-key-here
   
2. Rotate keys regularly

   Generate new API keys periodically and revoke old ones to minimize security risks.

3. Use environment-specific keys

   Create separate API keys for development, staging, and production environments.

4. Monitor key usage

   Track which keys are being used and revoke any that are no longer needed.

Integration

Shell/cURL

export FLEXPRICE_API_KEY="your-api-key"
curl -H "X-API-Key: $FLEXPRICE_API_KEY" \
  http://localhost:8080/v1/customers

Alternative Authentication Methods

Customer Portal Sessions

For customer-facing portal access, use session tokens instead of API keys:

Create Session

curl -X GET http://localhost:8080/v1/customers/portal/cus_external_123 \
  -H "X-API-Key: your-api-key"

This returns a temporary session token that customers can use to access their portal without exposing your API key.

Webhook Authentication

Public webhook endpoints don’t require API keys but use other verification methods (signatures, tenant/environment IDs in the URL).

Next Steps

Error Handling

Learn about API error codes and responses

API Overview

Understand the API structure and resources