API Authentication

This page defines how clients authenticate to the Geoportal API and how the API responds to authentication and authorization failures.

/* TODO: add information on API keys. Add information in enterprise and if they qualify. */

Scope

This reference focuses on API behavior and client expectations. It intentionally avoids sensitive implementation details.

Authentication Model

Geoportal API authentication is session-based for browser clients:

• The API is the trust boundary.
• Successful sign-in establishes a secure server-managed session.
• The browser receives a secure session cookie.
• Protected endpoints validate session and permissions on every request.

Transport and Client Requirements

• API authentication traffic must use HTTPS/TLS.
• Browser clients must send credentials (cookies) with requests.
• Cross-origin clients must be explicitly allowed by API CORS policy.

Sign-In and Session Lifecycle

Personal Account (Email + Password)

1. Client submits credentials over HTTPS.
2. API validates credentials and account status.
3. API creates session and sets secure cookie.
4. Client calls protected endpoints with cookie-based session.

Enterprise Account (Microsoft Entra ID SSO)

1. Client starts SSO flow.
2. User authenticates with Microsoft Entra ID.
3. API validates the identity response.
4. API creates Geoportal session and sets secure cookie.
5. Client calls protected endpoints with cookie-based session.

Protected Endpoints

Protected endpoints require a valid authenticated session.

If authentication succeeds, authorization is still evaluated per endpoint (organization access, roles, and permissions).

Standard Response Semantics

Use these semantics consistently across protected routes:

Status	Meaning	Client Action
200 / 2xx	Request authorized and successful	Continue normal flow.
401 Unauthorized	Authentication missing, expired, or invalid	Redirect to login or restart auth flow.
403 Forbidden	Authenticated but not permitted for resource/action	Show access denied or request elevated access.
401 Unauthorized	Expired Credentials	API returns 401 Unauthorized. Session is treated as no longer valid. Client should prompt user to sign in again.
401 Unauthorized	Invalid or Tampered Credentials	API returns 401 Unauthorized. API does not expose sensitive validation details in client-facing responses. Events are logged and monitored for abuse detection.

Session Security Characteristics

Geoportal session cookies are configured for secure browser use:

• HttpOnly to prevent JavaScript access.
• Secure to require HTTPS transport.
• SameSite to reduce cross-site request risk.
• Bounded session lifetime with expiration handling.

Compatibility Notes

• This API reference is authentication-system agnostic at the protocol level.
• Internal provider configuration and identity plumbing may evolve.
• Public client behavior and status-code contract in this page are the stable integration surface.