Authentication

Unauthenticated Endpoints

The Get Deck endpoint (GET /v1/decks/{deckId}) does not require an API key. It is intentionally unauthenticated so that Tabletop Simulator and similar tools can fetch deck data directly without credential management. All other endpoints require authentication as described below.

Getting an API Key

API keys are handed out on a case-by-case basis. Send an email to engineering@endlessgalaxy.dev with your project and use case to request an API key.

Key Format

Keys follow the format:

slvd_live_<hex>

where <hex> is a long hexadecimal string. Keep your key confidential — treat it like a password.

Making Authenticated Requests

Pass your key in the X-API-Key request header on every request:

curl https://api.sleeved.gg/v1/games/digimon/meta \
  -H "X-API-Key: slvd_live_your_key_here"

There is no bearer token scheme, no OAuth flow, and no session cookie. Every request must carry the header independently.

Authentication Errors

The API returns three distinct error shapes for authentication failures. The status code is 401 for missing/invalid keys and 429 for rate-limit exhaustion.

Missing API key (401)

The X-API-Key header is absent or empty:

{
  "error": "API key required"
}

This signals an SDK or transport bug — the request never carried a credential at all. It is not the same as "the key was rejected"; partners should treat this as a client-side defect to fix, not a credential-rotation event.

Invalid or revoked API key (401)

The header is present but the key is unknown, malformed, or has been revoked:

{
  "error": "Invalid API key"
}

Unknown and revoked keys deliberately return the identical error body. Distinguishing between these cases in the partner-visible response would leak information about which keys exist. If you receive this and your key was previously working, the key may have been revoked — email engineering@endlessgalaxy.dev.

Rate limit exceeded (429)

The key is valid but has consumed its per-window quota. See Rate Limiting for handling guidance:

{
  "error": "Rate limit exceeded"
}

What partners can rely on

• The error string is stable. Partner SDKs may parse the error field to drive retry/escalation logic.
• Status code + error string together identify the case. A 401 with body "API key required" is a missing-header bug; 401 with "Invalid API key" is a credential issue; 429 is back-pressure.
• The 401 cases do NOT distinguish unknown-vs-revoked in the response body. That distinction exists only in internal operator logs and is not partner-visible.

Operator log posture

Internal logs distinguish the underlying reason for a 401 (e.g., reason=missing|not_found|revoked) for debugging and incident response. These logs may be shipped to operator tooling (Sentry, Datadog, or similar). If your organization ships Sleeved-related operator logs to a third-party sink, restrict access to that sink — anyone with broad log-read access can infer key validity by correlating reason=not_found vs reason=revoked events. This is an operator-side concern, not a partner-visible information leak through the API response itself.

Security Recommendations

• Store your API key in an environment variable, not in source code
• Never expose your key in client-side JavaScript — all API calls should be made server-side
• Rotate your key if you suspect it has been compromised