Authentication
Real-time multiplayer server discovery — secure every API request with scoped API keys and OAuth 2.0.
API Keys
Every ServerPulse integration starts with an API key. Keys are generated from your dashboard, scoped to specific permissions, and attached to requests via a standard Bearer header.
Log in to dashboard.serverpulse.io, navigate to Settings → API Keys, and click Generate Key. You will be prompted to select the scopes your service requires before the key is issued.
Available Scopes
servers:read — Query server listings, filter by game, region, or player count.
servers:write — Register or update your own server entries in the directory.
players:read — Access player profiles, session history, and cross-server stats.
stats:read — Retrieve aggregate analytics, uptime reports, and latency metrics.
Key Structure
Production keys begin with sp_live_ followed by 32 hexadecimal characters. Sandbox keys use the sp_test_ prefix and never touch live infrastructure.
Example: sp_live_a4f2c8e1b9d37f06582e1a7c4b9d3f08
Authentication Header
Attach your key to every request via the Authorization header:
Authorization: Bearer sp_live_a4f2c8e1b9d37f06582e1a7c4b9d3f08
Requests without a valid key receive a 401 Unauthorized response. Insufficient scope returns 403 Forbidden.
OAuth 2.0
OAuth 2.0 is required when your application needs to access player-specific data on behalf of a logged-in user — such as personalized server recommendations, private session history, or cross-server player profiles.
ServerPulse implements the Authorization Code Grant flow with PKCE. Register your application at dashboard.serverpulse.io → OAuth Apps to receive a client ID and client secret.
Authorization Endpoint
GET https://auth.serverpulse.io/oauth/authorize
Redirect users here with your client_id, redirect_uri, scope, state, and code_challenge parameters. ServerPulse presents a consent screen listing the requested permissions before the user approves.
Token Exchange
POST https://auth.serverpulse.io/oauth/token
Exchange the authorization code for an access token and refresh token. Include your client_id, client_secret, code, code_verifier, and redirect_uri in the JSON request body.
Token Management
Access tokens expire after 1 hour. Use the refresh token to obtain a new access token without re-prompting the user. Refresh tokens remain valid for 30 days or until the user revokes access from their ServerPulse account settings.
OAuth tokens carry the same scope system as API keys — request only the minimum scopes your application needs.
Security Best Practices
Protect your keys and tokens with the same rigor you apply to production credentials. A leaked key can expose server lists, player data, or allow unauthorized server registrations at scale.
Environment Variables & Secrets Managers
Never hard-code API keys in source files or commit them to version control. Use environment variables or a dedicated secrets manager such as HashiCorp Vault, AWS Secrets Manager, or Doppler. If a key appears in a public repository, rotate it immediately and review the exposure window.
Principle of Least Privilege
Create separate keys for each service or environment. A background analytics worker should never hold servers:write scope. If a single key is compromised, narrow scopes limit the blast radius and reduce the time needed to contain the incident.
Rotate Keys Every 90 Days
ServerPulse supports up to two active keys per scope group, so generate the replacement key before revoking the existing one to avoid downtime. Schedule rotation as a recurring task in your deployment pipeline.
Enforce HTTPS
All ServerPulse endpoints enforce TLS 1.2 or higher. Never send API keys or tokens over unencrypted HTTP. Client-side applications should never store production keys — use OAuth 2.0 with PKCE for browser-based flows instead.
Usage Alerts & Anomaly Detection
Enable API usage alerts in your dashboard. Unusual spikes — such as a sudden burst of players:read calls from an unfamiliar IP range — may indicate a leaked credential. ServerPulse sends email and webhook notifications when anomalous patterns are detected.
Restrict Redirect URIs
Register only the exact redirect URIs your application uses. Wildcard matching is not supported. This prevents attackers from capturing authorization codes by registering a malicious redirect endpoint and hijacking the OAuth flow.