API Key Management

For production applications, Opacity recommends using permanent API keys to generate temporary JWT tokens. This approach provides enhanced security by ensuring that temporary tokens expire automatically, reducing the risk of unauthorized access if a token is compromised.

Overview

Instead of using your permanent API key directly in client-side code or long-running processes, you can use it to generate short-lived JWT tokens that expire automatically. This follows security best practices by limiting the exposure window of your credentials.

Getting Your Permanent API Key

1. Navigate to the API Keys section in your Opacity dashboard
2. Create a new permanent API key or use an existing one
3. Store this key securely in your server environment variables

While your permanent API key can be used for development and testing it is recommended to generate your token highlighted in Step 2.

Step 2: Generate Temporary JWT Tokens

Use your permanent API key to generate temporary JWT tokens by calling the /generate-jwt endpoint:

Endpoint

POST https://api.opacity.network/generate-jwt

Headers

{
  "Authorization-Provider": "opacity",
  "Authorization": "Bearer YOUR_API_KEY"
}

Example Implementation

const generateTemporaryToken = async (apiKey: string): Promise<string> => {
  const headers = {
    'Authorization-Provider': 'opacity',
    Authorization: `Bearer ${apiKey}`,
  }

  try {
    const response = await fetch('https://api.opacity.network/generate-jwt', {
      method: 'POST',
      headers,
    })

    if (!response.ok) {
      throw new Error(`Failed to generate JWT: ${response.statusText}`)
    }

    const data = (await response.json()) as { jwt: string; expires: string }

    if (!data.jwt) {
      throw new Error('No JWT returned from server')
    }

    return data.jwt
  } catch (error) {
    console.error('Error generating temporary token:', error)
    throw error
  }
}

// Usage
const temporaryToken = await generateTemporaryToken(process.env.OPACITY_API_KEY)

Response Format

A successful response (HTTP 200) returns:

{
  "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires": "2025-09-11T18:36:16.456Z"
}

You can now use your jwt response in place of your permanent API key.

Security Benefits

• Limited Exposure: Temporary tokens expire automatically, reducing security risks
• Credential Protection: Your permanent API key stays secure on your server
• Audit Trail: Each JWT generation can be tracked and monitored
• Access Control: Temporary tokens can have specific scopes and permissions

Best Practices

1. Server-Side Generation: Always generate JWTs on your backend server, never in client-side code
2. Environment Variables: Store your permanent API key in secure environment variables
3. Token Refresh: Implement automatic token refresh logic before expiration
4. Error Handling: Include proper error handling for network failures and API errors
5. Monitoring: Log JWT generation for security auditing

Error Handling

Handle common error scenarios:

• 401 Unauthorized: Invalid or expired permanent API key
• 403 Forbidden: Insufficient permissions for the requested operation
• 429 Too Many Requests: Rate limiting applied
• 500 Internal Server Error: Temporary service issues

Always implement retry logic with exponential backoff for transient errors.