API Documentation

Appearance

Engagifii Identity API Documentation ​

Table of Contents ​

Project Overview ​

The Engagifii Identity API is a comprehensive OAuth 2.0 and OpenID Connect authentication service that provides centralized identity management and single sign-on (SSO) capabilities for the Engagifii platform. Built on industry-standard protocols, this service enables secure authentication and authorization for both internal microservices and external applications.

Core Capabilities ​

  • OAuth 2.0 Authentication: Industry-standard authorization framework supporting multiple grant types
  • OpenID Connect (OIDC): Identity layer on top of OAuth 2.0 for authentication
  • Single Sign-On (SSO): Seamless authentication across all Engagifii services
  • Multi-tenant Support: Secure tenant isolation with organization-specific configurations
  • Token Management: JWT-based access and refresh token lifecycle management
  • User Management: Comprehensive user profile and permission management
  • Session Management: Secure session handling with logout capabilities
  • External Integration: Support for third-party application authentication

Key Features ​

  • Standard Protocols: Full OAuth 2.0 and OpenID Connect compliance
  • Multiple Grant Types: Support for Authorization Code, Client Credentials, and Refresh Token flows
  • JWT Tokens: Self-contained, cryptographically signed tokens
  • PKCE Support: Enhanced security for public clients
  • Token Introspection: Validate and inspect token claims
  • Discovery Endpoint: Auto-configuration for OpenID Connect clients
  • Customizable Scopes: Fine-grained permission control

Quick Start Guide ​

Get up and running with the Engagifii Identity API in under 5 minutes:

1. Get Your Credentials ​

Contact your system administrator to obtain:

  • Client ID: Your application identifier
  • Client Secret: Your application secret key (for confidential clients)
  • Redirect URI: Your application's callback URL (for authorization code flow)

2. Authorization Code Flow (For Web Applications) ​

bash
# Step 1: Redirect user to authorization endpoint
https://engagifii-identity-live.azurewebsites.net/connect/authorize?
  client_id=YOUR_CLIENT_ID&
  scope=openid profile email&
  redirect_uri=YOUR_REDIRECT_URI&
  response_type=code

# Step 2: Exchange authorization code for tokens
curl -X POST "https://engagifii-identity-live.azurewebsites.net/connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code&code=AUTH_CODE&redirect_uri=YOUR_REDIRECT_URI&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

3. Client Credentials Flow (For Service-to-Service) ​

bash
# Get an access token for service communication
curl -X POST "https://engagifii-identity-live.azurewebsites.net/connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&scope=api"

4. Next Steps ​

Base URLs ​

EnvironmentBase URLDescription
Productionhttps://engagifii-identity-live.azurewebsites.netLive production environment
QA/Staginghttps://engagifii-qa-identity.azurewebsites.netPre-production testing
Developmenthttps://engagifii-dev-identity.azurewebsites.netDevelopment and integration testing

Note: All OAuth/OIDC endpoints follow standard paths (e.g., /connect/authorize, /connect/token).

API Versioning ​

The Engagifii Identity API follows OAuth 2.0 and OpenID Connect specifications:

Current Implementation ​

  • OAuth 2.0: RFC 6749 compliant
  • OpenID Connect: Core 1.0 specification
  • Status: Stable and fully supported
  • Discovery: /.well-known/openid-configuration

Standard Endpoints ​

Authorization: /connect/authorize
Token: /connect/token
UserInfo: /connect/userinfo
Discovery: /.well-known/openid-configuration
JWKS: /.well-known/openid-configuration/jwks
Introspection: /connect/introspect
Revocation: /connect/revocation
End Session: /connect/endsession

Backward Compatibility ​

  • Standard protocol adherence ensures long-term compatibility
  • Token format changes will be communicated with migration period
  • Deprecated flows will be supported for at least 12 months

Support Information ​

Documentation Resources ​

Interactive Tools ​

Getting Help ​

  • Technical Documentation: Review our comprehensive guides above
  • Integration Examples: Check sample implementations for various platforms
  • Security Issues: Report security vulnerabilities through secure channels only
  • Support: Contact your system administrator for assistance

Security Considerations ​

  • Always use HTTPS for all authentication requests
  • Store client secrets securely (never in client-side code)
  • Implement proper token storage and rotation
  • Use PKCE for public clients (SPAs, mobile apps)
  • Validate tokens on the server side
  • Implement proper logout flows

Documentation Navigation ​

This documentation is organized into focused sections for different aspects of identity integration:

For New Developers ​

  1. Getting Started - Complete onboarding guide
  2. Authentication - OAuth flows and security setup
  3. Quick Reference - Essential endpoints and examples

For Integration Development ​

  1. API Reference - Complete endpoint documentation
  2. Error Handling - Error management strategies
  3. Integration Examples - Code samples and patterns

For Advanced Use Cases ​

  1. Token Management - Token lifecycle and validation
  2. Session Management - SSO and logout flows
  3. Postman Collection - Pre-built OAuth requests

Last Updated: Generated for Identity Service v1.0 Protocol Version: OAuth 2.0 / OpenID Connect 1.0 Documentation Version: 1.0.0

Copyright © 2025 Engagifii