CORS Authentication

CORS (Cross-Origin Resource Sharing) authentication allows browser-based applications to access the Subfrost API without exposing API keys in client-side code.

How It Works

  1. You register your domain in the Subfrost dashboard
  2. When requests come from your domain, the Origin header is verified
  3. If the origin matches a verified domain, the request is authenticated
  4. CORS headers are added to allow browser access

Setting Up CORS

Step 1: Add Your Domain

  1. Go to the Domains page in your dashboard
  2. Click "Add Domain"
  3. Enter your domain (e.g., https://myapp.com)

Step 2: Verify Ownership

For security, you may need to verify domain ownership:

DNS Verification: Add a TXT record to your domain's DNS:

_subfrost.yourdomain.com TXT "subfrost-verify=abc123xyz"

File Verification: Host a verification file at:

https://yourdomain.com/.well-known/subfrost-verify.txt

Step 3: Make Requests

Once verified, make requests from your domain:

// From https://myapp.com
const response = await fetch('https://mainnet.subfrost.io/v4/jsonrpc', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'btc_getblockcount',
    params: [],
    id: 1
  })
});

Supported Patterns

Exact Domain Match

https://myapp.com

Subdomain Wildcard

https://*.myapp.com

Matches:

  • https://www.myapp.com
  • https://api.myapp.com
  • https://staging.myapp.com

Development Domains

For local development, you can add:

http://localhost:3000
http://localhost:5173
http://127.0.0.1:3000

Note: Localhost domains don't require verification but should be removed before production.

CORS Headers

The API returns appropriate CORS headers:

Access-Control-Allow-Origin: https://myapp.com
Access-Control-Allow-Methods: POST, OPTIONS
Access-Control-Allow-Headers: Content-Type
Access-Control-Max-Age: 86400

Preflight Requests

The API handles OPTIONS preflight requests automatically:

// Browser automatically sends OPTIONS first
OPTIONS /v4/api HTTP/1.1
Origin: https://myapp.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: content-type

// API responds with CORS headers
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://myapp.com
Access-Control-Allow-Methods: POST, OPTIONS
Access-Control-Allow-Headers: Content-Type

Security Considerations

Advantages of CORS Auth

  • No API keys in browser code
  • Origin header can't be spoofed by browsers
  • Domain verification prevents unauthorized access
  • Works with CSP (Content Security Policy)

Limitations

  • Only works from browsers
  • Server-side requests need API keys
  • Doesn't work from browser extensions

Best Practices

  1. Only register production domains
  2. Remove localhost entries before production
  3. Use exact matches when possible
  4. Monitor domain usage in analytics

Troubleshooting

"CORS Error" in Browser

Check that:

  1. Your domain is registered and verified
  2. You're using the correct endpoint (/v4/api)
  3. The Origin header matches exactly

Request Works in Postman but Not Browser

Postman doesn't enforce CORS. Add your domain to the dashboard.

Preflight Failing

Ensure you're not sending custom headers that require preflight approval.

Combining with API Keys

You can use both CORS and API keys:

// CORS for origin verification + API key for rate limit bucket
const response = await fetch('https://mainnet.subfrost.io/v4/jsonrpc', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-subfrost-api-key': 'a1b2c3d4e5f67890a1b2c3d4e5f67890'  // Optional
  },
  body: JSON.stringify({ /* ... */ })
});