ShortyyDocs
Dashboard

Authentication & API Keys

Learn how to securely authenticate requests with Shortyy using Bearer tokens, granular scopes, and cryptographic hashing.

Authentication & API Keys

Shortyy authenticates all public REST API requests using high-entropy API keys. Every key is prefixed with sh_live_ to prevent accidental commits and simplify secret scanner detection.

Bearer Token Authentication

Include your API key in the standard HTTP Authorization header prefixed with Bearer :

http
GET /v1/links HTTP/1.1
Host: api.shortyy.com
Authorization: Bearer sh_live_48hexcharacters...
Accept: application/json

Alternative X-API-Key Header

For legacy proxies or environments where the Authorization header is intercepted, Shortyy also supports the X-API-Key header:

http
POST /v1/links HTTP/1.1
Host: api.shortyy.com
X-API-Key: sh_live_48hexcharacters...
Content-Type: application/json

Granular Scopes

Shortyy enforces strict Principle of Least Privilege (PoLP) through granular API key scopes:

ScopePermission GrantedExample Endpoints
links:writeCreate and shorten new URLsPOST /v1/links
links:readInspect links, list user links, fetch metadataGET /v1/links, GET /v1/links/:id
links:deleteRevoke/delete existing short linksDELETE /v1/links/:id
analytics:readView click metrics, referrers, and geo dataGET /v1/links/:id/analytics
user:readView account profile, plan tier, and quotasGET /v1/me, GET /v1/me/plan

If a request attempts an action outside the key's provisioned scopes, the API immediately returns HTTP 403 Forbidden:

json
{
  "error": {
    "code": "FORBIDDEN",
    "message": "API key lacks required scope: links:write",
    "status": 403
  }
}

Key Storage & Cryptography

▪
Entropy: Keys are generated using 24 cryptographically random bytes (48 hexadecimal characters) from Node.js crypto.randomBytes.
▪
SHA-256 Hashing: Only the cryptographic SHA-256 hash (api_keys.key_hash) is persisted to PostgreSQL. Shortyy staff and database administrators can never reconstruct your secret key.
▪
Safe Prefixes: The database records prefix (e.g. sh_live_6a5a...d862) for dashboard identification and audit logging.