API Security

Security Overview

GeoServer employs a multi-layered security architecture to protect your geospatial data and API endpoints. Our security model follows the principle of least privilege and supports multiple authentication strategies.

Authentication Flow

Every request to the GeoServer API follows this security pipeline. Understanding the flow helps you implement the right authentication method for your use case.

API Key Authentication

API keys are the simplest way to authenticate your application with the GeoServer API. Each key is tied to your account and can be scoped to specific permissions.

Generating an API Key

Navigate to your Dashboard → Settings → API Keys to generate a new key. Each key consists of a prefix and a secret:

// Your GeoServer API key structure
key:   geo_live_4f8a2b...     # Public key ID
secret: ••••••••••••••••  # Never share thisCopy

Using API Keys in Requests

Include your API key in the Authorization header using the Bearer scheme:

GET /api/v3/layers HTTP/1.1
Host: api.geoserver.io
Authorization: Bearer geo_live_4f8a2b...
X-API-Version: 2025-01
Content-Type: application/jsonCopy

Key Scopes & Permissions

OAuth 2.0 Authentication

For user-facing applications, GeoServer supports the OAuth 2.0 Authorization Code flow with PKCE (Proof Key for Code Exchange) for enhanced security.

Authorization Code Flow with PKCE

GET https://api.geoserver.io/oauth2/authorize?
  response_type=code
  client_id=your_client_id
  redirect_uri=https://yourapp.com/callback
  scope=layers:read maps:read
  code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  code_challenge_method=S256
  state=random_csrf_tokenCopy

POST https://api.geoserver.io/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7
redirect_uri=https://yourapp.com/callback
client_id=your_client_id
code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXkCopy

Token Response

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dBjftJeZ4CVP-mB92K27uhb...",
  "scope": "layers:read maps:read"
}Copy

JWT Token Configuration

GeoServer supports JSON Web Tokens (JWT) with RS256 and ES256 signing algorithms. JWTs can include custom claims for fine-grained authorization decisions.

Token Structure

{
  "iss": "https://api.geoserver.io",
  "sub": "usr_2a8b4c",
  "aud": "geo-api-v3",
  "exp": 1737648000,
  "iat": 1737644400,
  "scopes": ["layers:read", "maps:read"],
  "org_id": "org_9f3e1a",
  "jti": "a1b2c3d4-e5f6-7890"
}Copy

Custom Claims

You can add custom claims to JWTs for organization-specific authorization logic:

Rate Limiting

To ensure fair usage and protect infrastructure, GeoServer API endpoints enforce rate limits. Limits vary by plan and endpoint type.

Rate Limit Headers

Every API response includes rate limit information:

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1737648000
X-RateLimit-Window: 3600Copy

Rate Limits by Plan

Security Best Practices

Follow these guidelines to maximize the security of your GeoServer API integration:

1. Use environment variables — Store API keys and secrets in environment variables or a secrets manager, never in source code.
2. Enable TLS certificate pinning — For mobile and desktop applications, pin the GeoServer TLS certificate to prevent MITM attacks.
3. Implement token rotation — Rotate API keys and refresh tokens on a regular schedule. We recommend every 90 days.
4. Use the principle of least privilege — Only request the scopes your application actually needs. Avoid admin:full in production.
5. Enable audit logging — Monitor all API activity through the audit log endpoint and set up alerts for anomalous behavior.
6. Validate all inputs — Sanitize user-provided data before passing it to GeoServer endpoints to prevent injection attacks.
7. Implement retry logic with backoff — Handle rate limiting gracefully with exponential backoff (starting at 1s, doubling up to 60s).
8. Use signed requests for sensitive operations — Enable HMAC request signing for write operations involving sensitive geospatial data.

Request Signing Example

For high-security operations, sign your requests with HMAC-SHA256:

// JavaScript example
const crypto = require('crypto');

// Construct the signing string
const timestamp = Math.floor(Date.now() / 1000);
const method = 'POST';
const path = '/api/v3/layers';
const bodyHash = crypto.createHash('sha256').update(JSON.stringify(body)).digest('hex');

const signingString = `${method}\n${path}\n${timestamp}\n${bodyHash}`;

// Create the signature
const signature = crypto
  .createHmac('sha256', process.env.GEOSERVER_SECRET)
  .update(signingString)
  .digest('base64');

// Include in request headers
const headers = {
  'X-API-Key': process.env.GEOSERVER_API_KEY,
  'X-Signature-Timestamp': timestamp,
  'X-Signature': signature,
  'X-Content-Hash': bodyHash
};Copy

Security Error Responses

Authentication and authorization failures return specific HTTP status codes with descriptive error messages:

// Example error response
HTTP/1.1 403 Forbidden
{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "The 'layers:write' scope is required for this operation.",
    "required_scopes": ["layers:write"],
    "granted_scopes": ["layers:read", "maps:read"],
    "request_id": "req_8f3a2b1c"
  }
}Copy