GN HIP API Governance
Version: 1.0
Last Updated: July 7, 2025
Applies to: Internal and external consumers of GN APIs hosted on Azure API Management
Overview
GN’s APIs are built to be secure, scalable, and standards-compliant. This document provides guidance and governance rules that all internal and external application developers must follow when integrating with our APIs through Azure API Management (APIM).
Getting Started
To begin consuming GN APIs, follow these steps:
- Register your application with GN’s API Gateway team.
- Receive your Client ID and Client Secret.
- Implement authentication using OAuth 2.0 Client Credentials Flow.
- Review and adhere to API schema and format standards.
- Monitor key rotation schedules and integrate secure token management.
Authentication and Authorization
GN APIs are secured using industry-standard OAuth 2.0. All clients are required to authenticate before accessing protected resources.
OAuth 2.0 Client Credentials Flow
We use the Client Credentials Grant Flow for machine-to-machine communication. This flow requires a client application to authenticate using its Client ID and Client Secret to obtain an access token.
Token lifetime: 1 hour
Grant Type:client_credentials
Audience / Scope: Defined per API
Learn more: Microsoft Identity Platform - Client Credentials Flow
Token Management
- Access tokens are valid for 1 hour.
- It is strongly recommended that applications cache tokens and only request a new one upon expiry.
- Use a centralized token management service or middleware layer where feasible.
Bypassing OAuth
OAuth bypass is allowed only under exceptional circumstances with a documented and approved justification. In such cases:
- A Subscription Key will be issued.
- The subscription key must be auto-rotated every 90 days.
- APIs must still be protected through usage throttling and IP restrictions.
External Partner Authentication
- Client Secrets will be rotated every 90 days.
- A 5-day advance window will be provided before expiry.
- Updated secrets will be delivered through secure communication channels.
- Partners must implement fallback or redundancy to support seamless rollover.
Data Standards and Formats
Supported Data Types
| Format | Description |
|---|---|
| JSON | Preferred for modern APIs |
| XML | Supported for legacy and structured |
| Text | Supported for simple key-value data |
EDI Standards
For transactional and B2B flows, we support the following EDI document formats:
- EDIFACT (Electronic Data Interchange for Administration, Commerce, and Transport)
- ANSI X12 (Accredited Standards Committee X12)
- ROSETTANET (A open e-business process standards)
Communication Protocols
| Protocol | Use Case |
|---|---|
| AS2 | Secure, reliable B2B communication |
| HTTPS | Default transport for all API transactions |
| TLS Mutual Auth | Certificate-based authentication supported |
Security and Credential Rotation
Credential security is paramount. All secrets and keys must be rotated on a defined schedule.
| Credential Type | Rotation Frequency | Notes |
|---|---|---|
| OAuth Client Secret | Every 90 days | 5-day early distribution to external partners |
| Subscription Key | Every 90 days | Used only with explicit approval |
API Schema Validation
- Schema validation is required on all public and partner-facing APIs.
- APIs must publish:
- JSON Schema for request/response payloads.
- OpenAPI (Swagger) specifications.
- Schema validation ensures:
- Predictable behavior
- Clear error handling
- Strong typing and backward compatibility
Best Practices
- ✅ Use OAuth and cache tokens to reduce overhead and improve performance.
- ✅ Implement retry logic with exponential backoff.
- ✅ Log API errors and metrics for monitoring and alerting.
- ✅ Minimize payload size for optimal performance.
- ✅ Validate inputs and sanitize outputs to prevent injection and logic flaws.
- ❌ Do not hardcode secrets or tokens in source code or config files.
- ❌ Do not bypass schema validation unless approved.
Contact and Support
- For API onboarding and credentials: IntegrationSupport@gn.com
- For security incidents: IntegrationSupport@gn.com
- For technical documentation and integration help: GN Developer Portal
© 2025 GN Corporation. All rights reserved.