API Reference
Authentication and API Keys
Pre-launch
Section
API Reference
Documentation category
Type
Guide
Technical reference
Summary
How to obtain a SwssChain Explorer API key via SWSS DevHub, authenticate requests, and handle authentication errors.
SWSS Foundation Notice

This documentation is restricted to authorised members of the SWSS Developer Community. Access is granted exclusively through SWSS DevHub, after KYB and SWSS Foundation approval.

All SwssChain GitHub repositories are private. Significant updates are currently deploying across the full SWSS Ecosystem. SDK and API specifications are subject to change at any time in accordance with security requirements and SwssChain Foundation governance decisions.

Join SWSS DevHub →Have a question? Use the Need Help? button below.
SDK Update Notice

SWSS SDK v2.1 is deploying across the ecosystem. API signatures may change during this period. Ensure your integration uses the latest schema from SWSS DevHub.

Article Content

Authentication and API Keys

The SwssChain Explorer API uses API key authentication. All requests to the API must include a valid API key obtained via SWSS DevHub. API keys are tied to your DevHub developer account and carry the rate limit allocation associated with your tier. Every API key is unique, auditable, and should be treated as a sensitive credential.

Obtaining an API Key

  1. Apply for a developer account through SWSS DevHub, and complete KYB and SWSS Foundation approval.
  2. Complete the developer verification process.
  3. Navigate to the API Keys section of your DevHub dashboard.
  4. Click Generate New Key and select your intended usage (mainnet, testnet, or both).
  5. Copy and securely store the key: it is displayed in full only once.

Base URLs

EnvironmentBase URL
Mainnethttps://swssscan.swss.io/api/v1
Testnethttps://swssscan.swss.io/testnet/api/v1

Authenticating Requests

Include your API key in the X-API-Key header on every request. This is the preferred authentication method for all server-side integrations:

curl https://swssscan.swss.io/api/v1/blocks/latest   -H "X-API-Key: your_api_key_here"

For simple read-only GET requests, the API key may also be passed as a query parameter. This is acceptable for quick testing but should not be used in production code where the URL may be logged:

curl "https://swssscan.swss.io/api/v1/blocks/latest?apiKey=your_api_key_here"

API Key Security Rules

  • Never expose your API key in client-side code, browser JavaScript, or public repositories
  • Never commit API keys to version control: store in environment variables only
  • Use separate keys for development, staging, and production environments
  • Rotate keys regularly via the DevHub dashboard: revoke any key that may have been compromised
  • Each key has its own independent rate limit allocation: high-volume production traffic should not share a key with development workloads

Authentication Error Responses

HTTP StatusCondition
401 UnauthorizedAPI key missing from request or key is invalid
403 ForbiddenValid key but insufficient permissions for this endpoint
429 Too Many RequestsRate limit for this key's tier has been exceeded

All error responses share the same JSON structure:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key",
    "timestamp": "2026-05-15T10:00:00Z",
    "requestId": "req_abc123xyz"
  }
}

The requestId field can be provided to the SWSS DevHub support team to investigate specific request failures.

Next Steps

Frequently Asked Questions
6 questions
Where do I get an API key?

From the SWSS DevHub dashboard, after your developer application has completed KYB and been approved. See Developer and Validator Access.

I lost my key. Can it be shown again?

No. A key is displayed in full once at generation. Generate a new one and revoke the old.

Can I pass the key as a query parameter?

It is accepted for quick testing but should not be used in production, where URLs are frequently logged by proxies, load balancers and error trackers. Use the X-API-Key header.

What is the difference between 401 and 403?

401 means the key is missing or invalid. 403 means the key is valid but does not carry permission for that endpoint: usually a tier your approval does not cover.

How do I report a failing request?

Every error response carries a requestId. Quote it to SWSS DevHub support; it identifies the exact request without you having to reproduce it.

Is one key enough for mainnet and testnet?

A key is scoped at generation. Generate separately for each network unless you selected both, and prefer separate keys regardless so usage is attributable per environment.