Authentication

NetLoc8 uses API keys to authenticate requests. All authenticated endpoints accept the key via the X-API-Key header.

API Key Types

NetLoc8 provides two types of API keys for different use cases:

Secretsk_live_...

Full API access. Use server-side only — never expose in client bundles or version control.

  • All scopes by default
  • No origin restrictions
  • Account, billing, and geo access
Publishablepk_live_...

Safe for client-side use. Restricted to geo lookups and requires allowed origins.

  • geo:read scope only
  • Requires allowed origin patterns
  • Safe to include in browser bundles

Never expose secret keys

Secret keys (sk_live_...) grant full account access. Never include them in client-side code, public repositories, or browser bundles. Use publishable keys for browser-side geolocation.

Using API Keys

Pass your key in the X-API-Key header:

Bash
curl -H "X-API-Key: sk_live_YOUR_KEY" \
  https://api.netloc8.com/v1/ip/me

Or use the SDK — it handles authentication automatically:

JavaScript
import { fetchGeo } from '@netloc8/core';

const geo = await fetchGeo('8.8.8.8', {
    apiKey: process.env.NETLOC8_API_KEY,
});

Scopes

Secret keys can be restricted to specific scopes. By default, secret keys have all scopes. Publishable keys are always limited to geo:read.

ScopeAccess
geo:readIP geolocation and timezone lookups
account:readRead profile, keys, and usage data
account:writeCreate/revoke keys, manage sites
billing:readRead subscription and plan data
billing:writeCreate checkout sessions, cancel subscriptions

Allowed Origins

Publishable keys require at least one allowed origin. The API validates the Origin header against your configured patterns.

Supported patterns include exact match and wildcard subdomains:

JSON
[
    "https://example.com",
    "https://*.example.com",
    "http://localhost:3000"
]

Development origins

Add http://localhost:3000 (or your dev port) to allowed origins during development. Remove it before going to production.

Bearer Token Authentication

Alternatively, you can authenticate with a session bearer token from the auth service. This is primarily used by the dashboard:

Bash
# 1. Sign in
curl -X POST https://auth.netloc8.com/api/auth/sign-in/email \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "..."}'

# 2. Use the token
curl https://api.netloc8.com/v1/ip/me \
  -H "Authorization: Bearer <token>"

For most integrations, API keys are simpler and recommended. Bearer tokens are useful for dashboard-style applications that already have a user session.

Key Management

Manage API keys through the dashboard or the API:

  • Create: POST /v1/account/me/keys — the raw key is returned once; store it securely.
  • List: GET /v1/account/me/keys — returns metadata only (prefix, name, status). Raw keys are never returned again.
  • Revoke: DELETE /v1/account/me/keys/{keyId} — permanently revokes a key.
  • Renew: POST /v1/account/me/keys/{keyId}/renew — extends expiration. Free-plan keys expire after 1 year.

See the Account API Reference for full request/response details.