Skip to main content

​
Authentication Overview

Ozura Vault supports multiple authentication methods depending on your use case.

​
Authentication Methods

​
1. API Key Authentication

Best for: Server-to-server integrations, backend services, automated systems API keys are passed in the X-API-Key header: 
curl -X POST https://pci-vault-hrhwdgc4akhse3bs.eastus-01.azurewebsites.net/tokenize \
  -H "X-API-Key: key_your_application_api_key" \
  -H "Content-Type: application/json" \
  -d '{"type": "card", "data": {...}}'
Supported endpoints:
  • POST /tokenize - Create tokens
  • POST /detokenize - Retrieve original data
  • POST /proxy/transaction - Forward to PSPs
  • POST /internal/provision - Create sub-projects (requires provisioning permission)
  • GET /api/applications/key - Verify API key

​
2. JWT Token Authentication

Best for: Dashboard access, user-facing applications, web interfaces JWT tokens are passed either as a cookie or in the Authorization header: 
# Using Authorization header
curl -X GET https://pci-vault-hrhwdgc4akhse3bs.eastus-01.azurewebsites.net/tokens \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

# Or via HTTP-only cookie (set automatically after login)
Supported endpoints:
  • All dashboard/management endpoints
  • Token listing and management
  • Project and application management
  • Audit log access
  • User settings

​
3. Hybrid Authentication

Best for: Team members using API keys with user attribution You can combine both methods - the API key authenticates the request, while the JWT token identifies the user for audit logging: 
curl -X POST https://pci-vault-hrhwdgc4akhse3bs.eastus-01.azurewebsites.net/tokenize \
  -H "X-API-Key: key_your_application_api_key" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"type": "card", "data": {...}}'
This logs the action under the authenticated user rather than the project owner.

​
API Key Security

​
Best Practices

  1. Never expose API keys in client-side code 
    // BAD - Don't do this in browser JavaScript
fetch('/tokenize', { headers: { 'X-API-Key': 'key_abc123' } })

// GOOD - Call from your backend server
  2. Use environment variables 
    export OZURA_API_KEY="key_your_api_key"
  3. Rotate keys periodically
    • Create a new application
    • Update your integration
    • Delete the old application
  4. Use separate keys per environment
    • Production project → Production API key
    • Staging project → Staging API key

​
Key Format

API keys follow this format: 
key_{app_name}_{region}_{type}_{random}
Example: key_myapp_us_pvt_a1b2c3d4e5f6

​
JWT Token Details

​
Token Structure

JWT tokens contain: 
{
  "sub": "user_id",
  "project_id": "proj_abc123",
  "email": "user@example.com",
  "role": "owner",
  "mfa_required": false,
  "mfa_enabled": true,
  "mfa_verified": true,
  "exp": 1706270400
}

​
Token Lifetime

Token TypeLifetimeRefresh
Access Token24 hoursRe-login required
Cookie15 minutesAuto-refreshed on activity

​
MFA Enforcement

If MFA is enabled, the token includes MFA status:
  • mfa_required: Whether MFA must be verified
  • mfa_enabled: Whether user has MFA set up
  • mfa_verified: Whether MFA was verified this session
Protected endpoints return 403 if mfa_required=true but mfa_verified=false.

​
Rate Limiting

Authentication endpoints have specific rate limits:
EndpointLimit
POST /auth/login5 requests / 2 minutes
POST /auth/register30 requests / hour
GET /auth/verify60 requests / minute
POST /auth/change-password3 attempts / hour
See Error Handling for handling rate limit responses.

​
Next Steps

  • API Keys - Managing application API keys
  • JWT Tokens - User authentication flow
  • MFA - Multi-factor authentication