API Reference

Table of Contents

• Overview
• Base URLs
• Authentication Endpoints
• Token Endpoints
• User Information Endpoints
• Discovery Endpoints
• Session Management Endpoints
• Token Introspection
• Request/Response Formats

Overview

The Engagifii Identity API implements OAuth 2.0 (RFC 6749) and OpenID Connect Core 1.0 specifications. All endpoints follow standard protocol definitions with additional custom extensions for enhanced functionality.

API Conventions

• Protocol: HTTPS only (TLS 1.2+)
• Request Format: application/x-www-form-urlencoded for OAuth endpoints
• Response Format: JSON (UTF-8 encoded)
• Date Format: ISO 8601 (YYYY-MM-DDTHH:mm:ssZ)
• Error Format: OAuth 2.0 error response format

Base URLs

Environment	Base URL
Production	https://engagifii-identity-live.azurewebsites.net
Development	https://engagifii-sandbox-identityservice.azurewebsites.net

Authentication Endpoints

Authorization Endpoint

Initiates the authorization code flow for user authentication.

GET /connect/authorize

Request Parameters

Parameter	Type	Required	Description
client_id	string	Yes	The client identifier
response_type	string	Yes	Must be code for authorization code flow
redirect_uri	string	Yes	Callback URL (must match registered URI)
scope	string	Yes	Space-separated list of scopes
state	string	Recommended	Opaque value for CSRF protection
nonce	string	Recommended	Unique value for replay protection (OpenID Connect)
response_mode	string	No	How authorization response is returned (query, fragment, form_post)
prompt	string	No	User interaction preference (none, login, consent)
max_age	integer	No	Maximum authentication age in seconds
ui_locales	string	No	Preferred UI languages
login_hint	string	No	Hint about user's identity
acr_values	string	No	Authentication context class references
code_challenge	string	PKCE	Base64url-encoded SHA256 hash of verifier
code_challenge_method	string	PKCE	Must be S256

Example Request

GET /connect/authorize?
  client_id=webapp&
  response_type=code&
  redirect_uri=https://app.example.com/callback&
  scope=openid profile email&
  state=abc123&
  nonce=n-0S6_WzA2Mj

Success Response

Redirect to callback with authorization code:

https://app.example.com/callback?
  code=AUTHORIZATION_CODE&
  state=abc123

Error Response

Redirect to callback with error:

https://app.example.com/callback?
  error=access_denied&
  error_description=User denied access&
  state=abc123

Token Endpoints

Token Endpoint

Exchanges authorization codes for tokens or refreshes existing tokens.

POST /connect/token

Request Headers

Content-Type: application/x-www-form-urlencoded

Grant Types

Authorization Code

Parameter	Type	Required	Description
grant_type	string	Yes	Must be authorization_code
code	string	Yes	Authorization code from authorize endpoint
redirect_uri	string	Yes	Must match authorize request
client_id	string	Yes	Client identifier
client_secret	string	Confidential	Client secret
code_verifier	string	PKCE	Original code verifier

Example Request:

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

grant_type=authorization_code&
code=abc123&
redirect_uri=https://app.example.com/callback&
client_id=webapp&
client_secret=secret

Client Credentials

Parameter	Type	Required	Description
grant_type	string	Yes	Must be client_credentials
client_id	string	Yes	Client identifier
client_secret	string	Yes	Client secret
scope	string	No	Requested scopes

Example Request:

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

grant_type=client_credentials&
client_id=service&
client_secret=secret&
scope=api.read api.write

Refresh Token

Parameter	Type	Required	Description
grant_type	string	Yes	Must be refresh_token
refresh_token	string	Yes	The refresh token
client_id	string	Yes	Client identifier
client_secret	string	Confidential	Client secret
scope	string	No	Reduced scope (optional)

Example Request:

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

grant_type=refresh_token&
refresh_token=def502...&
client_id=webapp&
client_secret=secret

Success Response

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "def50200a7f9f5d3...",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "scope": "openid profile email"
}

Error Response

{
  "error": "invalid_grant",
  "error_description": "The provided authorization code is invalid or has expired"
}

Token Revocation Endpoint

Revokes access or refresh tokens.

POST /connect/revocation

Request Parameters

Parameter	Type	Required	Description
token	string	Yes	Token to revoke
token_type_hint	string	No	Hint about token type (access_token or refresh_token)
client_id	string	Yes	Client identifier
client_secret	string	Confidential	Client secret

Example Request

POST /connect/revocation
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(client_id:client_secret)

token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...&
token_type_hint=access_token

Success Response

HTTP/1.1 200 OK

User Information Endpoints

UserInfo Endpoint

Returns claims about the authenticated user.

GET /connect/userinfo
POST /connect/userinfo

Request Headers

Authorization: Bearer ACCESS_TOKEN

Success Response

{
  "sub": "248289761001",
  "name": "Jane Doe",
  "given_name": "Jane",
  "family_name": "Doe",
  "preferred_username": "j.doe",
  "email": "janedoe@example.com",
  "email_verified": true,
  "picture": "https://example.com/janedoe/photo.jpg",
  "updated_at": "2024-01-15T10:30:00Z"
}

Error Response

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token", error_description="The access token expired"

Discovery Endpoints

OpenID Connect Discovery

Returns OpenID Connect configuration metadata.

GET /.well-known/openid-configuration

Success Response

{
  "issuer": "https://engagifii-identity-live.azurewebsites.net",
  "authorization_endpoint": "https://engagifii-identity-live.azurewebsites.net/connect/authorize",
  "token_endpoint": "https://engagifii-identity-live.azurewebsites.net/connect/token",
  "userinfo_endpoint": "https://engagifii-identity-live.azurewebsites.net/connect/userinfo",
  "end_session_endpoint": "https://engagifii-identity-live.azurewebsites.net/connect/endsession",
  "check_session_iframe": "https://engagifii-identity-live.azurewebsites.net/connect/checksession",
  "revocation_endpoint": "https://engagifii-identity-live.azurewebsites.net/connect/revocation",
  "introspection_endpoint": "https://engagifii-identity-live.azurewebsites.net/connect/introspect",
  "device_authorization_endpoint": "https://engagifii-identity-live.azurewebsites.net/connect/deviceauthorization",
  "jwks_uri": "https://engagifii-identity-live.azurewebsites.net/.well-known/openid-configuration/jwks",
  "response_types_supported": [
    "code",
    "token",
    "id_token",
    "code id_token",
    "code token",
    "id_token token",
    "code id_token token"
  ],
  "response_modes_supported": [
    "query",
    "fragment",
    "form_post"
  ],
  "grant_types_supported": [
    "authorization_code",
    "client_credentials",
    "refresh_token",
    "implicit",
    "urn:ietf:params:oauth:grant-type:device_code"
  ],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["RS256"],
  "scopes_supported": [
    "openid",
    "profile",
    "email",
    "address",
    "phone",
    "offline_access",
    "api"
  ],
  "token_endpoint_auth_methods_supported": [
    "client_secret_basic",
    "client_secret_post",
    "private_key_jwt"
  ],
  "claims_supported": [
    "sub",
    "name",
    "family_name",
    "given_name",
    "middle_name",
    "nickname",
    "preferred_username",
    "profile",
    "picture",
    "website",
    "email",
    "email_verified",
    "gender",
    "birthdate",
    "zoneinfo",
    "locale",
    "phone_number",
    "phone_number_verified",
    "address",
    "updated_at"
  ],
  "code_challenge_methods_supported": ["S256"],
  "request_parameter_supported": true,
  "request_object_signing_alg_values_supported": ["RS256"]
}

JSON Web Key Set (JWKS)

Returns the public keys used to verify JWT signatures.

GET /.well-known/openid-configuration/jwks

Success Response

{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "kid": "1234567890",
      "x5t": "...",
      "e": "AQAB",
      "n": "...",
      "x5c": ["..."],
      "alg": "RS256"
    }
  ]
}

Session Management Endpoints

End Session Endpoint

Initiates logout and terminates the user session.

GET /connect/endsession
POST /connect/endsession

Request Parameters

Parameter	Type	Required	Description
id_token_hint	string	Recommended	ID token for identifying session
post_logout_redirect_uri	string	No	URL to redirect after logout
state	string	No	Opaque value returned in redirect

Example Request

GET /connect/endsession?
  id_token_hint=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...&
  post_logout_redirect_uri=https://app.example.com/logout-complete&
  state=abc123

Success Response

Redirect to post-logout URI:

https://app.example.com/logout-complete?state=abc123

Check Session Endpoint

Provides an iframe for checking session status (for SPAs).

GET /connect/checksession

Returns HTML page with JavaScript for session monitoring.

Token Introspection

Introspection Endpoint

Validates and returns information about a token.

POST /connect/introspect

Request Parameters

Parameter	Type	Required	Description
token	string	Yes	Token to introspect
token_type_hint	string	No	Hint about token type
client_id	string	Yes	Client identifier
client_secret	string	Yes	Client secret

Example Request

POST /connect/introspect
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(client_id:client_secret)

token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Success Response

Active token:

{
  "active": true,
  "scope": "openid profile email",
  "client_id": "webapp",
  "username": "jane.doe",
  "exp": 1672531200,
  "iat": 1672527600,
  "nbf": 1672527600,
  "sub": "248289761001",
  "aud": ["api1", "api2"],
  "iss": "https://engagifii-identity-live.azurewebsites.net",
  "jti": "JTI123456"
}

Inactive token:

{
  "active": false
}

Request/Response Formats

Standard Error Response

All OAuth endpoints return errors in this format:

{
  "error": "error_code",
  "error_description": "Human-readable error description",
  "error_uri": "https://docs.example.com/errors/error_code"
}

Common Error Codes

Error Code	Description
invalid_request	Request missing required parameter or malformed
invalid_client	Client authentication failed
invalid_grant	Authorization code or refresh token invalid
unauthorized_client	Client not authorized for grant type
unsupported_grant_type	Grant type not supported
invalid_scope	Requested scope invalid or exceeds granted scope
access_denied	Resource owner denied request
unsupported_response_type	Response type not supported
server_error	Server encountered unexpected error
temporarily_unavailable	Server temporarily unable to handle request

JWT Token Structure

Access and ID tokens are JWTs with three parts:

Header

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "1234567890"
}

Payload (Access Token)

{
  "nbf": 1672527600,
  "exp": 1672531200,
  "iss": "https://engagifii-identity-live.azurewebsites.net",
  "aud": ["api1", "api2"],
  "client_id": "webapp",
  "sub": "248289761001",
  "auth_time": 1672527600,
  "idp": "local",
  "scope": ["openid", "profile", "email"],
  "amr": ["pwd"],
  "jti": "JTI123456",
  "iat": 1672527600
}

Payload (ID Token)

{
  "nbf": 1672527600,
  "exp": 1672531200,
  "iss": "https://engagifii-identity-live.azurewebsites.net",
  "aud": "webapp",
  "nonce": "n-0S6_WzA2Mj",
  "iat": 1672527600,
  "auth_time": 1672527600,
  "sub": "248289761001",
  "name": "Jane Doe",
  "given_name": "Jane",
  "family_name": "Doe",
  "email": "jane.doe@example.com",
  "email_verified": true,
  "amr": ["pwd"],
  "idp": "local"
}

Rate Limiting

API endpoints implement rate limiting:

Endpoint Type	Rate Limit	Window
Authorization	10 requests	Per minute per IP
Token	20 requests	Per minute per client
UserInfo	100 requests	Per minute per token
Discovery	100 requests	Per minute per IP

Rate limit headers:

X-RateLimit-Limit: 20
X-RateLimit-Remaining: 15
X-RateLimit-Reset: 1672531200

CORS Configuration

For browser-based applications:

Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type
Access-Control-Max-Age: 3600

---

Next Steps: Review Error Handling for comprehensive error management strategies.