API Authentication

Authentication Overview

All requests to the SHA224.com API must be authenticated. We use API keys to authenticate requests and provide different access levels based on your subscription plan.

To get started with the SHA224.com API:

1. Sign up for an account at app.sha224.com/signup
2. Navigate to the API Keys section in your dashboard
3. Generate your API key
4. Use this key in your API requests

API Key Authentication

The API uses HTTP Bearer Authentication with API keys. Include your API key in the Authorization header of your HTTP requests.

Header Format

Authorization: Bearer YOUR_API_KEY

Example Request

curl -X POST https://api.sha224.com/v1/hash/text \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello, world!"}'

Types of API Keys

SHA224.com offers different types of API keys for various use cases:

You can generate multiple API keys for different purposes or services. This helps you maintain security by allowing you to rotate or revoke keys without affecting other systems.

API Key Management

Effective API key management is important for security and operational efficiency.

Creating API Keys

1. Log in to your SHA224.com account
2. Navigate to Settings > API Keys
3. Click "Create New API Key"
4. Select the key type and provide a description
5. For client keys, specify allowed domains
6. Copy and store your new key securely

Revoking API Keys

If a key is compromised or no longer needed, revoke it immediately:

1. Log in to your SHA224.com account
2. Navigate to Settings > API Keys
3. Find the key you want to revoke
4. Click "Revoke Key"
5. Confirm the revocation

Revoked keys cannot be restored. You'll need to create a new key if needed.

Key Rotation

Regularly rotating API keys is a security best practice. We recommend rotating your keys every 90 days:

1. Create a new API key
2. Update your applications to use the new key
3. Verify everything is working with the new key
4. Revoke the old key

Client-Side API Keys

For web applications that need to make API requests directly from the browser, you can use client API keys. These keys have restricted permissions and can be restricted to specific domains.

Domain Restrictions

Client keys can only be used from domains that you specify when creating the key. This prevents unauthorized use if the key is exposed.

// Example of using a client key in a browser application
const hashText = async (text) => {
  const response = await fetch('https://api.sha224.com/v1/hash/text', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer CLIENT_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ text })
  });
  return response.json();
};

Securing Client Keys

Best practices for using client keys:

• Only use client keys for non-sensitive operations
• Always set domain restrictions
• Set low rate limits for client keys
• For sensitive operations, proxy requests through your server
• Monitor client key usage for unusual patterns

Server-Side Proxy Pattern

For improved security, we recommend using the server-side proxy pattern for most applications:

// Backend proxy in Node.js/Express
const express = require('express');
const axios = require('axios');
const app = express();

app.use(express.json());

// Your server-side route that proxies to SHA224 API
app.post('/api/hash', async (req, res) => {
  try {
    const response = await axios.post('https://api.sha224.com/v1/hash/text', {
      text: req.body.text
    }, {
      headers: {
        'Authorization': `Bearer ${process.env.SHA224_API_KEY}`,
        'Content-Type': 'application/json'
      }
    });
    
    res.json(response.data);
  } catch (error) {
    res.status(500).json({ error: 'Hash generation failed' });
  }
});

app.listen(3000, () => console.log('Server running on port 3000'));

# Backend proxy in Python/Flask
import os
import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/api/hash', methods=['POST'])
def hash_text():
    data = request.json
    
    try:
        response = requests.post(
            'https://api.sha224.com/v1/hash/text',
            json={'text': data.get('text')},
            headers={
                'Authorization': f'Bearer {os.environ.get("SHA224_API_KEY")}',
                'Content-Type': 'application/json'
            }
        )
        
        return jsonify(response.json())
    except Exception as e:
        return jsonify({'error': 'Hash generation failed'}), 500

if __name__ == '__main__':
    app.run(debug=True)

<?php
// Backend proxy in PHP
header('Content-Type: application/json');

$data = json_decode(file_get_contents('php://input'), true);

$ch = curl_init('https://api.sha224.com/v1/hash/text');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['text' => $data['text']]));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . getenv('SHA224_API_KEY'),
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode >= 400) {
    http_response_code(500);
    echo json_encode(['error' => 'Hash generation failed']);
} else {
    echo $response;
}
?>

In this pattern, your client makes requests to your server, which then makes authenticated requests to the SHA224.com API. This keeps your API key secure on your server.

JWT Authentication (Enterprise)

For Enterprise customers, we offer JWT-based authentication for more flexible and fine-grained access control:

JWT Overview

JSON Web Tokens (JWTs) allow you to:

• Create short-lived tokens with specific permissions
• Delegate access to specific resources
• Implement custom authentication flows
• Define granular access controls

Creating JWTs

// Node.js example of creating a JWT for SHA224.com API
const jwt = require('jsonwebtoken');

const createApiToken = () => {
  const payload = {
    sub: 'user_id',
    iss: 'your_app_id',
    permissions: ['hash:create', 'hash:verify'],
    exp: Math.floor(Date.now() / 1000) + (60 * 15) // 15 minutes
  };
  
  return jwt.sign(payload, process.env.SHA224_JWT_SECRET, { algorithm: 'HS256' });
};

// Use the token in API requests
const token = createApiToken();
// Authorization: Bearer <token>

For more information on Enterprise JWT authentication, please contact our sales team.

OAuth 2.0 Integration (Enterprise)

Enterprise customers can also use OAuth 2.0 to integrate SHA224.com with their existing authentication systems.

OAuth Flow

1. Register your application in the SHA224.com dashboard
2. Implement the OAuth 2.0 authorization code flow
3. Receive authentication tokens
4. Use the access token to authenticate API requests

For detailed OAuth 2.0 integration instructions, see our Enterprise OAuth Guide.

Security Best Practices

Store API Keys Securely

• Use environment variables, not hardcoded values
• Use secrets management services (AWS Secrets Manager, HashiCorp Vault, etc.)
• Never commit API keys to version control

Implement Proper Access Controls

• Use the principle of least privilege
• Create separate keys for different services
• Regularly rotate API keys

Monitor API Usage

• Set up alerts for unusual activity
• Review API logs regularly
• Use the SHA224.com dashboard to monitor API usage

Handle Errors Properly

• Implement retry logic with exponential backoff
• Handle authentication errors appropriately
• Don't expose detailed error messages to end users

Network Security

• Always use HTTPS for API requests
• Consider using IP whitelisting (available on Pro and Enterprise plans)
• Use a VPN or private network connection for sensitive applications

Authentication Troubleshooting

Next Steps