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-dev.hydrigital.com/docs/device",
    "verification_uri_complete": "https://auth-dev.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
  "exp": 1640995200,         // Expiration (max 60 seconds)
  "iat": 1640995140          // Issued at
}
            

Key Requirements

• Algorithm: RS256 (RSA with SHA-256)
• Key Size: Minimum 2048 bits
• Expiration: Maximum 60 seconds
• Unique ID: Each JWT must have a unique `jti` claim

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

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_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