Skip to main content

API Reference Overview

Identix IDP Broker provides a comprehensive set of REST APIs for managing the platform, authenticating users, and integrating with other systems. All APIs are designed to be modern, secure, and developer-friendly.

API Categories​

Identix APIs are categorized into several functional areas:

  • Admin API: Manage tenants, users, identity providers, and system configurations.
  • Auth API: Core authentication and authorization endpoints (OAuth2, OIDC, SAML).
  • Public API: Unauthenticated endpoints for login, registration, and discovery.
  • User API: End-user self-service APIs for profile and security management.
  • Integration API: Manage third-party integrations and connectors.

Base URLs​

  • Local Development: http://localhost:8080/
  • Production: https://<your-domain>/

Authentication​

  • Admin & User APIs: Require a valid JWT bearer token in the Authorization header.
  • Auth APIs: Use standard OAuth2/OIDC authentication flows.
  • Public APIs: No authentication required, but may be protected by reCAPTCHA or rate limiting.

Key Endpoints​

Admin APIs​

  • GET /api/admin/users: List and search users.
  • POST /api/admin/idp-configs: Configure a new federated identity provider.
  • GET /api/admin/audit-logs: Access system-wide audit logs.
  • PUT /api/admin/branding: Update platform branding and styling.

Auth APIs​

  • GET /oauth2/authorize: Initiate an OAuth2/OIDC authorization flow.
  • POST /oauth2/token: Exchange an authorization code for tokens.
  • GET /oauth2/jwks: Retrieve the public keys used to sign JWTs.
  • GET /.well-known/openid-configuration: OIDC discovery endpoint.

Public APIs​

  • POST /auth/login: Authenticate a user with local credentials.
  • POST /auth/register: Register a new user account.
  • GET /auth/discovery: Discover available authentication methods and providers.
  • POST /auth/password/reset: Initiate the password reset process.

User APIs​

  • GET /api/user/profile: Retrieve the current user's profile.
  • PATCH /api/user/profile: Update profile information.
  • POST /api/user/mfa/enroll: Enroll a new MFA method.
  • DELETE /api/user/sessions: Revoke an active user session.

Error Handling​

Identix uses standard HTTP status codes for error reporting:

  • 200 OK: Successful request.
  • 400 Bad Request: Validation error or invalid parameters.
  • 401 Unauthorized: Authentication failed or token is missing/expired.
  • 403 Forbidden: Authenticated user lacks the necessary permissions.
  • 404 Not Found: Requested resource does not exist.
  • 500 Internal Server Error: An unexpected error occurred on the server.

Error responses typically include a JSON body with a descriptive message and error code:

{
  "error": "invalid_request",
  "error_description": "The 'client_id' parameter is missing."
}

Interactive API Documentation​

Identix includes integrated Swagger UI for interactive exploration and testing of the Admin and User APIs.

  • Access URL: http://localhost:8080/swagger-ui.html (Local development)