Supra Core API — Public Client Documentation

Chapter 03 — Authentication

1. Authentication Purpose

The Supra Core API service is commercial and authenticated. A valid API key associated with an enabled plan identifies the authorized client and its assigned access policy.

From a public client perspective, an API key:

• permits authenticated requests;
• identifies your integration;
• can be subject to access restrictions and rate limits;
• must be treated as a secret;
• can be rotated or replaced if exposed.

Authentication does not give access to wallets, funds, signing, trading, or write operations.

---

2. Authentication Method

Send the API key in either X-API-Key or the standard Bearer authorization header. Every request, including health, requires authentication.

Every credential shown below is a placeholder and must be replaced only inside your protected client environment.

curl -sS \
  -H 'X-API-Key: <api-key>' \
  '<api-base>/api/v1/health'

Equivalent Bearer form:

curl -sS \
  -H 'Authorization: Bearer <api-key>' \
  '<api-base>/api/v1/health'

2.1 Use HTTPS

Use the HTTPS API base supplied for your access.

HTTPS protects the request in transit. It does not protect a key that is:

• committed to source control;
• embedded in public code;
• written to logs;
• included in screenshots;
• copied into an insecure message.

2.2 Do not use query strings

Do not send:

<api-base>/api/v1/health?api_key=<api-key>

Keys in URLs can leak through:

• browser history;
• access logs;
• analytics;
• referrer headers;
• monitoring tools;
• copied links.

Important: Send the credential only through one of the documented headers. Do not send both unless the provider explicitly asks you to diagnose credential transport.

---

3. Basic Authenticated Request

Request:

GET <api-base>/api/v1/health
X-API-Key: <api-key>

Curl:

curl -sS \
  -H 'X-API-Key: <api-key>' \
  '<api-base>/api/v1/health'

3.1 Illustrative JSON response

This response is shortened and illustrative:

{
  "ok": true,
  "data": {
    "status": "<status>",
    "server_time_utc": "<utc-timestamp>"
  },
  "meta": {
    "api_version": "v1",
    "endpoint": "health"
  }
}

A successful health request confirms basic API availability. It does not guarantee that every indexed or derived data set is current.

---

4. Where to Store the API Key

Store the key in a protected server-side location such as:

• a server environment secret;
• a managed secret manager;
• protected backend configuration;
• a CI/CD secret store;
• a deployment platform's encrypted secret facility.

Do not store it in:

• a public repository;
• committed .env content;
• public documentation;
• frontend source code;
• mobile application bundles;
• static website files;
• client-visible build variables;
• ordinary application logs.

Use access controls so only the service and authorized operators can read the secret.

Note: The name of a secret variable can appear in code. Its value must not.

---

5. Browser and Frontend Safety

Do not call Supra Core directly from public browser code when the request requires your API key.

Use this pattern:

browser frontend
    -> your backend/proxy
    -> Supra Core

Detailed flow:

<client-app>
    -> sends a public-safe request to <backend-url>
    -> backend validates the request
    -> backend reads <api-key> from secure storage
    -> backend calls <api-base> with X-API-Key
    -> backend filters/caches the response
    -> frontend receives public-safe JSON

The frontend must never receive the upstream key.

5.1 Why frontend hiding does not work

These methods do not protect a key:

• minification;
• obfuscation;
• bundling it in a hidden module;
• storing it in browser local storage;
• placing it in a frontend environment variable;
• encoding it.

Users can inspect browser code and network requests.

---

6. Mobile App Safety

Do not ship a long-lived API key inside a mobile application bundle.

Assume secrets embedded in an application can be extracted from:

• package files;
• application memory;
• debug output;
• network instrumentation;
• modified devices.

Recommended pattern:

mobile app
    -> your authenticated backend/session
    -> Supra Core

The backend applies your user policy and keeps the upstream credential private.

If a mobile-shipped key is discovered, treat it as exposed and rotate it.

---

7. Backend Proxy Pattern

The following language-agnostic pseudo-code illustrates a safe proxy:

function handleClientRequest(request):
    validateLocalUserAndRequest(request)

    apiKey = readSecret("<secure-secret-store>")

    upstream = httpGet(
        url = "<api-base>/api/v1/market/current?limit=20&offset=0",
        headers = {
            "X-API-Key": apiKey
        },
        timeout = configuredTimeout
    )

    parsed = parseJson(upstream.body)
    safeResponse = selectPublicFields(parsed)

    cacheWhenAppropriate(safeResponse)
    return safeResponse

The backend should:

• validate its own users where required;
• enforce its own abuse controls;
• set timeouts;
• cache common requests;
• redact upstream headers;
• return only data needed by the frontend;
• avoid forwarding private error detail.

It must never return the upstream API key.

---

8. Server-Side Bot or Analytics Job Pattern

A bot or analytics job can call Supra Core directly when it runs in a trusted server-side environment.

Recommended practices:

• load the key from a protected secret source;
• call the API over HTTPS;
• use the X-API-Key header;
• set request timeouts;
• limit polling frequency;
• cache or reuse recent results;
• redact authentication headers from logs;
• use bounded retries with jitter;
• handle empty and stale data gracefully.

Do not hardcode the key in the bot or job source.

---

9. What Authentication Does Not Provide

An authenticated Supra Core API request does not provide:

• wallet access;
• private keys;
• transaction signing;
• trading;
• swaps;
• order placement;
• fund movement;
• private user account access;
• blockchain transaction submission;
• guaranteed real-time freshness.

The API is read-oriented.

Authentication controls access to data endpoints. It does not authorize financial actions.

---

10. 401 Unauthorized

HTTP 401 means the API did not accept the request's authentication.

Public reasons can include:

• missing key;
• incorrect key;
• expired key;
• revoked key;
• key not authorized for the request;
• client IP not allowed for the key;
• key copied with unwanted whitespace or a newline.

The response can remain generic rather than reveal the exact lifecycle reason.

10.1 Illustrative 401 response

{
  "ok": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "<authentication-message>"
  }
}

10.2 Client action

When you receive 401:

1. stop aggressive retries;
2. confirm X-API-Key is present;
3. confirm your backend loaded the intended secret;
4. remove accidental whitespace/newlines;
5. confirm the API base URL;
6. contact the approved support channel if access may be expired or revoked.

Do not send the key to support.

Authentication is fail-closed: a missing, disabled, expired, IP-denied, or unknown key is rejected with 401. The service does not fall back to a different credential source after rejecting the submitted key.

---

11. 429 Is Not an Authentication Error

HTTP 429 means the request reached an applicable rate limit.

The key can be valid even though the request is rejected for excessive request frequency.

When you receive 429:

• back off;
• add jitter;
• reduce polling;
• cache shared responses;
• avoid parallel duplicate requests;
• retry later.

The response may not include Retry-After unless a later public contract explicitly documents it.

Do not replace a key merely because one request returned 429.

---

12. Key Exposure Response

Treat a key as exposed if it appears in:

• public source code;
• browser or mobile bundles;
• a shared screenshot;
• logs;
• a ticket or message;
• a public paste;
• a leaked build artifact.

12.1 Immediate response

1. Stop using and repeating the exposed value.
2. Remove it from public locations where possible.
3. Contact the project or provider through the approved support channel.
4. Request rotation or reissue using <rotation-contact>.
5. Update your backend with the replacement.
6. Check your own logs, repositories, build artifacts, and screenshots.
7. Verify the old key no longer works.

Deleting one visible copy does not make an exposed credential safe again.

Warning: Never paste the exposed key into the support request. Use <request-id> or another safe reference supplied by the provider.

---

13. Logging and Redaction

Never log the value of:

• X-API-Key;
• other authentication headers;
• the complete request header set when it contains secrets;
• secret-manager output.

Before sharing evidence, apply redaction.

Public-safe troubleshooting details can include:

• HTTP status;
• endpoint path;
• UTC timestamp;
• sanitized query parameters;
• public error code;
• <request-id>;
• a provider-supplied redacted key label.

Avoid screenshots containing:

• terminal commands with substituted keys;
• browser request headers;
• CI/CD secret output;
• mobile debug logs containing credentials.

---

14. CI/CD and Deployment Safety

14.1 Store as a deployment secret

Use:

• CI/CD secret variables;
• deployment platform secret storage;
• a managed secret system;
• protected environment-level values.

14.2 Prevent log exposure

• Do not echo secret values.
• Disable shell tracing around secret use.
• Review build scripts for header logging.
• Avoid printing environment variables.
• Redact failed request diagnostics.

14.3 Preview and fork environments

Confirm whether:

• preview deployments receive secrets;
• untrusted forks can execute workflows;
• build artifacts include generated configuration;
• third-party actions can access secret variables.

Use separate development, test, and production keys when available.

Rotate immediately after accidental build-log or artifact exposure.

---

15. API Key Security Checklist

• API key is stored server-side.
• HTTPS is used.
• X-API-Key is sent only by a trusted backend or server job.
• Browser frontend never receives the key.
• Mobile application does not bundle a long-lived key.
• Repository and .env files do not expose the key.
• CI/CD logs do not echo secrets.
• Application logs redact authentication headers.
• 401 stops aggressive retry.
• 429 uses backoff and caching.
• Transient failures use bounded retries.
• Key exposure and rotate procedure is known.
• Health is not treated as complete data freshness proof.

---

16. Common Mistakes

---

17. Troubleshooting Authentication

Use this public-safe checklist:

1. Verify the header name is exactly X-API-Key.
2. Verify the key was copied completely.
3. Check for leading/trailing whitespace or newline characters.
4. Verify the backend environment secret is loaded.
5. Verify the request actually passes through your backend/proxy.
6. Verify the request uses the correct <api-base>.
7. Compare the HTTP status:
   • 401: authentication was not accepted;
   • 429: rate limit was reached;
   • 500: unexpected server-side failure.
8. Confirm the key was not exposed and replaced.
9. Ask the provider whether the key is expired or revoked when needed.
10. Share only redacted evidence.

Do not:

• print the key;
• send full headers;
• expose your secret store;
• brute-force variations;
• disable your own security controls.

---

18. Scope and Data Exposure

Clients authenticate only with the documented X-API-Key or Authorization: Bearer <api-key> header. Responses expose client-visible authentication outcomes, while credential administration remains outside the API contract.

---

19. Chapter Summary

Authenticate Supra Core requests by sending:

X-API-Key: <api-key>

or:

Authorization: Bearer <api-key>

over HTTPS.

Keep the secret on a trusted backend, proxy, bot server, or analytics environment. Never embed it in browser or mobile frontend code, URLs, public repositories, logs, screenshots, or support messages.

HTTP 401 means authentication was not accepted and should not be retried aggressively. HTTP 429 means the request hit a rate limit; back off and cache rather than replacing the key. If a key is exposed, stop using it and request rotation through the approved provider process.

Authentication grants read access only. It does not provide wallet signing, trading, order placement, fund movement, private account access, or a guarantee of current data freshness.