API Reference

All API requests go through the API Gateway at http://localhost:8080.

Base URL & Headers

Environment	Base URL
Local development	`http://localhost:8080`
Production	`https://iam.yourdomain.com`

Required headers for protected endpoints:

Authorization: Bearer <access_token>
Content-Type: application/json
Accept: application/json

Authentication Endpoints

OIDC Discovery Document

GET /realms/{realm}/.well-known/openid-configuration

curl http://localhost:8080/realms/master/.well-known/openid-configuration | jq .

Authorization Endpoint (Authorization Code + PKCE)

GET /realms/{realm}/protocol/openid-connect/auth
    ?client_id=<id>
    &redirect_uri=<uri>
    &response_type=code
    &code_challenge=<S256_challenge>
    &code_challenge_method=S256
    &scope=openid+profile+email

Token Endpoint

POST /realms/{realm}/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

Token Operations

Client Credentials

curl -X POST http://localhost:8080/realms/master/protocol/openid-connect/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials" \
-d "client_id=my-service" \
-d "client_secret=<secret>"

Response:

{
"access_token": "eyJhbGci...",
"token_type": "Bearer",
"expires_in": 300,
"scope": "openid profile email"
}

Exchange Code for Tokens

curl -X POST http://localhost:8080/realms/master/protocol/openid-connect/token \
-d "grant_type=authorization_code" \
-d "code=<auth_code>" \
-d "redirect_uri=http://localhost:3000/callback" \
-d "code_verifier=<pkce_verifier>" \
-d "client_id=opengate-console"

Refresh Token

curl -X POST http://localhost:8080/realms/master/protocol/openid-connect/token \
-d "grant_type=refresh_token" \
-d "refresh_token=<refresh_token>" \
-d "client_id=opengate-console"

Introspect Token

curl -X POST http://localhost:8080/realms/master/protocol/openid-connect/token/introspect \
-d "token=<access_token>" \
-d "client_id=my-service" \
-d "client_secret=<secret>"

Error Reference

Error Response Formatjson

{
"timestamp": "2025-06-01T10:00:00Z",
"status": 404,
"error": "Not Found",
"message": "REALM_NOT_FOUND",
"path": "/api/realms/unknown-realm"
}

HTTP Status	Meaning	Common Cause
`400 Bad Request`	Validation failed	Missing required field, invalid format
`401 Unauthorized`	Missing or invalid JWT	Token expired, wrong issuer
`403 Forbidden`	Insufficient permissions	Wrong realm, missing role
`404 Not Found`	Resource missing	Wrong ID, deleted resource
`409 Conflict`	Already exists	Duplicate username/email/client_id
`422 Unprocessable`	Business rule violation	Weak password, disabled user
`500 Internal Error`	Server error	Check service logs

Rate limiting

The gateway applies rate limiting per IP. Default: 30 requests/minute. Exceeding the limit returns 429 Too Many Requests.