Hydrigital Authentication Server Documentation & API Reference

Quick Start Checklist

• Authentication Server: Auto-detected based on environment
• Client Registration: Obtain client credentials from your system administrator
• Redirect URI: Configure your application's callback URL
• Scopes: Determine the permissions your application needs - View Available Scopes
• Grant Type: Choose the appropriate OAuth2 flow for your application type

Application Types

• Web Applications: Use Authorization Code flow with client secret
• Single Page Applications (SPA): Use PKCE Authorization Code flow
• Mobile Applications: Use PKCE Authorization Code flow
• Server-to-Server: Use Client Credentials flow
• IoT/Device Applications: Use Device Authorization flow

Core OAuth2 Endpoints

• Authorization: oauth/authorize - Initiate OAuth2 flows
• Token: oauth/token - Exchange codes for tokens
• Token Revocation: oauth/revoke - Revoke access/refresh tokens
• Token Introspection: oauth/introspect - Validate token status
• Device Authorization: oauth/deviceauthorization - Device flow initiation
• User Info: oauth/userinfo - Get user information

Discovery Endpoints

• OpenID Configuration: /.well-known/openid_configuration
• OAuth2 Metadata: /.well-known/oauth-authorization-server
• JWKS: /.well-known/jwks.json

Session Management

• SSO Logout: oauth/logout - Single sign-out
• Session Check: /session/check - Validate session
• Session Info: /session/info - Get session details

Health & Status

• Health Check: /health - Server health status
• System Status: /status - Detailed system information
• Configuration: /config - Server configuration details

Authorization Code Flow

Use Case: Web applications with server-side components

Security: Most secure flow, requires client secret

// Step 1: Redirect user to authorization endpoint
GET /oauth/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=SCOPES&state=STATE

// Step 2: Exchange authorization code for tokens
POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id=CLIENT_ID
&client_secret=CLIENT_SECRET
&code=AUTHORIZATION_CODE
&redirect_uri=REDIRECT_URI
            

PKCE Authorization Code Flow

Use Case: Single Page Applications (SPAs) and mobile apps

Security: Secure for public clients, no client secret required

// Step 1: Generate PKCE parameters
code_verifier = base64url(random(32))
code_challenge = base64url(sha256(code_verifier))

// Step 2: Authorization request with PKCE
GET /oauth/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI
&scope=SCOPES&state=STATE&code_challenge=CHALLENGE&code_challenge_method=S256

// Step 3: Token exchange with code verifier
POST /oauth/token
grant_type=authorization_code&client_id=CLIENT_ID&code=AUTH_CODE
&redirect_uri=REDIRECT_URI&code_verifier=CODE_VERIFIER
            

Client Credentials Flow

Use Case: Server-to-server communication

Security: No user interaction, application-level access

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=CLIENT_ID
&client_secret=CLIENT_SECRET
&scope=SCOPES
            

Resource Owner Password Flow

Use Case: Trusted applications (legacy support)

Security: Lower security, only for trusted first-party apps

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=password
&client_id=CLIENT_ID
&client_secret=CLIENT_SECRET
&username=USERNAME
&password=PASSWORD
&scope=SCOPES
            

Device Authorization Flow (RFC 8628)

Use Case: Input-constrained devices (Smart TVs, IoT devices, etc.)

Security: Secure for devices without browsers or easy input methods

// Step 1: Request device code
POST /oauth/deviceauthorization
client_id=CLIENT_ID&scope=SCOPES

// Response:
{
    "device_code": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS",
    "user_code": "WDJB-MJHT",
    "verification_uri": "https://auth.hydrigital.com/docs/device",
    "verification_uri_complete": "https://auth.hydrigital.com/docs/device?user_code=WDJB-MJHT",
    "expires_in": 1800,
    "interval": 5
}

// Step 2: Poll for token
POST /oauth/token
grant_type=urn:ietf:params:oauth:grant-type:device_code
&client_id=CLIENT_ID
&device_code=DEVICE_CODE
            

Refresh Token Flow

Use Case: Refresh expired access tokens without user interaction

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&client_id=CLIENT_ID
&client_secret=CLIENT_SECRET  // Optional for PKCE flows
&refresh_token=REFRESH_TOKEN
            

Token Exchange Flow

Use Case: Exchange short-lived tokens for long-lived ones (60-day expiration)

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=exchange_token
&client_id=CLIENT_ID
&client_secret=CLIENT_SECRET  // Optional for PKCE flows  
&subject_token=SHORT_LIVED_ACCESS_TOKEN
            

Overview

JWT Client Assertion provides a more secure alternative to client secrets for confidential clients. Instead of a shared secret, clients use asymmetric cryptography with a private key to sign JWTs.

Benefits

• Enhanced Security: No shared secrets, uses public/private key cryptography
• Non-repudiation: Digital signatures provide proof of client identity
• Scalability: Public keys can be distributed without compromising security
• Standards Compliance: Follows RFC 7523 specification

Implementation

Replace client_secret with JWT client assertion in token requests:

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=CLIENT_ID
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=JWT_SIGNED_WITH_PRIVATE_KEY
&scope=SCOPES
            

JWT Structure

Header:
{
  "alg": "RS256",
  "typ": "JWT"
}

Payload:
{
  "iss": "CLIENT_ID",        // Issuer (client_id)
  "sub": "CLIENT_ID",        // Subject (client_id)
  "aud": "TOKEN_ENDPOINT",   // Audience (token endpoint URL)
  "jti": "UNIQUE_ID",        // Unique JWT ID (required)
  "exp": 1640995200,         // Expiration (max 300 seconds / 5 minutes)
  "iat": 1640995140          // Issued at
}
            

Key Requirements

• Algorithm: RS256 (RSA with SHA-256)
• Key Size: Minimum 2048 bits
• Expiration: Maximum 300 seconds (5 minutes) — assertions with exp − iat > 300 are rejected
• Unique ID (jti): Each JWT must have a unique jti claim to prevent replay attacks

Overview

The JWT Bearer Grant allows a trusted backend service to obtain an access token that represents a specific user, without requiring that user to interactively authenticate. The client presents a signed JWT assertion where iss identifies the client and sub identifies the user.

This is distinct from JWT Client Assertion (where iss=sub=client_id), which is a client authentication method. Here, the JWT is the grant itself.

Use Cases

• Service-to-service impersonation: A backend microservice acts on behalf of a user without requiring a user session
• Token bootstrapping: An internal identity provider issues signed claims that the auth server exchanges for access tokens
• Federated identity delegation: A trusted system presents a verified user identity to obtain scoped access

Request Format

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
&assertion=JWT_SIGNED_ASSERTION
&client_id=CLIENT_ID
&client_secret=CLIENT_SECRET   // or client_assertion (JWT Client Assertion)
&scope=SCOPES
            

JWT Assertion Structure

Header:
{
  "alg": "RS256",
  "typ": "JWT"
}

Payload:
{
  "iss": "CLIENT_ID",           // Issuer — must equal client_id
  "sub": "[email protected]",    // Subject — user email address or username
  "aud": "TOKEN_ENDPOINT",      // Audience — token endpoint URL
  "jti": "UNIQUE_ID",           // Unique JWT ID (prevents replay)
  "iat": 1640995140,            // Issued at
  "exp": 1640995440             // Expiration (max 300 seconds after iat)
}
            

User Resolution

The sub claim is resolved to a user account in the following order:

1. Email address lookup
2. Username lookup (fallback)

If no matching user is found, the assertion is rejected.

Key Requirements

• Grant type must be enabled: jwt_bearer is not enabled by default — it must be explicitly enabled per client in the application's grant policy
• Signature: The assertion must be signed with the client's registered private key (same key used for JWT Client Assertion)
• Algorithm: RS256, RS384, RS512, ES256, ES384, or ES512
• Issuer: iss must equal the client_id
• Audience: aud must be the token endpoint URL
• TTL: exp − iat must not exceed 300 seconds (5 minutes)
• Replay prevention: Each jti may only be used once

Endpoints

URL	Method	Use case
/oauth/logout	GET / POST	API / programmatic logout — requires Authorization: Bearer, returns JSON
/logout	GET	Browser-based session logout — reads session cookie, redirects user

API Logout — POST /oauth/logout

Χρησιμοποιείται από το backend της εφαρμογής για να ακυρώσει όλα τα tokens της session. Απαιτεί πάντα το Authorization: Bearer header.

POST /oauth/logout
Authorization: Bearer <access_token>

// Optional: also terminate web session (same as web logout)
logoutwebsession=1

// Success response (HTTP 200):
{
    "success": true
}

// Error response (invalid or missing token):
{
    "error": "Invalid token"
}
            

API Logout Parameters

Parameter	Type	Required	Description
logoutwebsession	Integer	No	When set to 1, OAuth logout also clears web session state (uid, user, logged) just like browser logout.

Note: Without logoutwebsession=1, /oauth/logout revokes OAuth tokens for the current OAuth session but does not force full browser session cleanup.

Browser Logout — GET /logout

Χρησιμοποιείται όταν ο χρήστης κάνει κλικ στο "Sign Out" στον browser. Δεν χρειάζεται Authorization header — διαβάζει το session cookie. Κάνει redirect μετά.

GET /logout

// Optional query parameters:
redirect_uri=https://your-app.com/  // Where to redirect after logout
local=1                             // Clears session but does NOT revoke tokens
            

What Happens on Logout

• The user's server session is destroyed
• All active tokens for the same session (sid) are revoked
• Registered applications are notified of the logout event (if configured)
• With local=1 (browser mode only): session is destroyed but tokens remain valid

Required Headers — API mode

Header	Value	Required
Authorization	Bearer <access_token>	Yes — χωρίς token επιστρέφει {"error":"Invalid token"}

OAuth2 Security Best Practices

• ✅ Always use HTTPS: Encrypt all communication with the authorization server
• ✅ Validate redirect URIs: Exact match including protocol, domain, port, and path
• ✅ Use state parameter: Prevent CSRF attacks in authorization code flows
• ✅ Implement proper token storage: Secure storage mechanisms for sensitive tokens
• ✅ Handle token expiration: Implement automatic refresh logic
• ✅ Use appropriate scopes: Request minimal necessary permissions
• ✅ Validate token responses: Always check for errors and validate token format
• ✅ Implement logout: Provide secure logout with token revocation

Flow-Specific Security

• ✅ PKCE for Public Clients: Always use PKCE for SPAs and mobile apps
• ✅ Client Secret Protection: Never expose client secrets in client-side code
• ✅ Device Flow Security: Display user codes securely, implement proper polling
• ✅ JWT Client Assertion: Use proper key management and rotation

Supported Security Features

• ✅ PKCE Support: RFC 7636 for public clients
• ✅ Token Revocation: RFC 7009 for immediate token invalidation
• ✅ Token Introspection: RFC 7662 for token validation
• ✅ Device Authorization: RFC 8628 for input-constrained devices
• ✅ OpenID Connect: Identity layer with standardized user info
• ✅ JWT Client Assertion: RFC 7523 for enhanced client authentication
• ✅ JWT Bearer Grant: RFC 7523 §2.1 for service-to-service delegated user identity

Available Scopes

Scopes define the permissions your application requests. Use the minimum scopes necessary for your application:

Scope	Description
Personal User Data
profile	Access to basic profile information (name, picture, etc.).
email	Access to the user's primary email address.
phone	Access to the user's phone number.
user	Access to user account information.
Account Actions
openid	Required for OpenID Connect requests.
offline_access	Allow the application to perform actions on your behalf even when you are not online.
General Entities
deya_read	Read access to DEYA (organization) information.
deya_manage	Full management access to DEYA information.
location_read	Read access to location data.
location_manage	Full management access to location data.
zone_read	Read access to water zone information.
zone_manage	Full management access to water zones.
route_read	Read access to water route information.
route_manage	Full management access to water routes.
supply_read	Read access to water supply information.
supply_manage	Full management access to water supply.
customer_read	Read access to customer information.
customer_manage	Full management access to customer data.
customer_export	Export customer data.
Urban Water
urbanwater:entity_read	Read access to Urban Water entities.
urbanwater:entity_write	Write access to Urban Water entities.
urbanwater:metric_read	Read access to Urban Water metrics.
urbanwater:metric_write	Write access to Urban Water metrics.
urbanwater:datapoint_read	Read access to Urban Water data points.
urbanwater:report_read	Read access to Urban Water reports.
urbanwater:report_write	Write access to Urban Water reports.
urbanwater:report_list	List available Urban Water reports.
urbanwater:report_execute	Execute Urban Water reports.
WCM
wcm:devices_read	Read access to WCM devices.
wcm:devices_encryptionkeys	Read WCM Devices encryption keys.
wcm:devices_write	Write access to WCM devices.
wcm:consumptions	Access to consumption data in WCM.
wcm:alerts_read	Read access to WCM alerts.
wcm:alerts_write	Write and manage WCM alerts.
WCM Importer
wcmimporter:import	Import data using WCM Importer.
wcmimporter:read	Read access to WCM Importer data.
Consumption Recorder
consumptionrecorder:record	Record consumption data.
consumptionrecorder:read	Read consumption records.
System & Administrative
system:admin	Administrative access to all systems.
system:audit_read	Read access to audit logs.
system:health	Access to system health and monitoring data.
system:mass_update	Perform mass update operations across systems.
system:notifications_read	Read user notifications.
system:notifications_write	Send and manage user notifications.

Client Configuration

• Client Type: Confidential (with secret) or Public (without secret)
• Grant Types: Allowed OAuth2 flows for the client
• Redirect URIs: Allowed callback URLs (exact match required)
• Scopes: Maximum allowed scopes for the client
• Token Lifetime: Access token expiration time
• Refresh Token: Whether refresh tokens are issued

Standard OAuth2 Errors

Error Code	Description	Common Causes
invalid_request	Request is malformed	Missing required parameters
invalid_client	Client authentication failed	Wrong client_id or client_secret
invalid_grant	Grant is invalid or expired	Expired authorization code
unauthorized_client	Client not authorized for grant type	Grant type not allowed for client
unsupported_grant_type	Grant type not supported	Invalid grant_type parameter
invalid_scope	Requested scope is invalid	Unknown or unauthorized scope
access_denied	User denied authorization	User clicked "deny" on consent screen

Error Response Format

{
    "error": "invalid_request",
    "error_description": "The request is missing the required parameter 'grant_type'.",
    "error_uri": "https://tools.ietf.org/html/rfc6749#section-5.2"
}
            

Best Practices for Error Handling

• 🔍 Parse error responses: Always check for error field in responses
• 🔍 Log errors appropriately: Log for debugging but don't expose sensitive info
• 🔍 Implement retry logic: For network errors and temporary failures
• 🔍 User-friendly messages: Translate technical errors to user-friendly messages
• 🔍 Fallback strategies: Implement graceful degradation for auth failures