Skip to content

Identity Platform API Overview

This document provides a high-level overview of the Identity Platform API surface for authentication, authorization, user management, federation, MFA, and token lifecycle operations. It is written for architects and engineers integrating with the Identity Platform.

The Identity Platform combines standards-based OpenID Connect / OAuth2 endpoints with platform APIs owned by the Authorization Server and Identity Backend. This is a conceptual overview - exact OpenAPI/Swagger documentation and implementation contracts live in product repositories and the technical documentation hub.

Note

This is a conceptual overview of the Identity Platform API. Concrete endpoint shape, request/response schemas, claims, scopes, and implementation contracts live in the Identity Platform product repository and ConnectSoft.Documentation.

API Surface at a Glance

The Identity Platform API provides endpoints for:

  • OIDC/OAuth Standards - Authorization, token, userinfo, discovery, JWKS, revocation, and introspection endpoints.
  • Identity Management - User registration, profile, credential, role, claim, and tenant membership APIs.
  • MFA and Recovery - Enrollment, verification, recovery codes, reset flows, and step-up challenges.
  • Federation and Account Linking - External provider configuration, login callback handling, account linking, and provider metadata.
  • Token Lifecycle - Refresh, revocation, introspection, key rollover support, and token audit visibility.
  • Admin APIs - Tenant identity policy, client administration, provider administration, and security operations.

Authentication and Authorization

OAuth2/OIDC Flows

  • Authorization Code with PKCE - Default interactive flow for Shell, MFEs, browser-hosted clients, mobile apps, and public clients
  • Client Credentials Flow - Service-to-service authentication
  • Device Authorization Flow - Optional for devices and constrained-input tools where approved
  • Resource Owner Password Flow - Deprecated and not a ConnectSoft default
  • Implicit Flow - Not supported for new ConnectSoft systems

Token Types

  • Access Tokens - Short-lived tokens for API access
  • Refresh Tokens - Long-lived tokens for token refresh
  • ID Tokens - OpenID Connect ID tokens
  • Service Access Tokens - Short-lived client credentials tokens for service-to-service calls

Authentication Methods

  • OAuth2/OIDC - Standard OAuth2/OIDC flows
  • Client Credentials - Confidential service clients with scoped access
  • Certificate-Based / mTLS - High-security service authentication where required
  • External IdP Federation - OIDC/SAML/social/enterprise providers brokered through the Identity Platform

Main Resource Groups

Resource Group Examples Notes
OIDC/OAuth /authorize, /token, /userinfo, /.well-known/openid-configuration, /jwks Standards endpoints owned by the Authorization Server
Users /users, /users/{id}, /users/{id}/profile Identity Backend user lifecycle operations
Tenants /tenants, /tenants/{id}, /tenants/{id}/settings Tenant management
Roles /roles, /roles/{id}, /roles/{id}/permissions Role and permission management
MFA /users/{id}/mfa, /mfa/challenges, /mfa/recovery-codes MFA enrollment, verification, and recovery
External IdPs /idps, /idps/{id}, /idps/{id}/federation Provider configuration and account linking
Tokens /tokens/introspect, /tokens/revoke Token validation and lifecycle management
Clients and Scopes /clients, /scopes, /consents Authorization Server administration

Common Usage Patterns

Pattern 1: Login via OpenID Connect

Steps: 1. Redirect user to authorization endpoint 2. User authenticates locally or through a federated provider 3. Receive authorization code 4. Exchange code for tokens 5. Shell or BFF uses access token for API calls through API Gateway

Example Flow: 

GET /authorize?client_id=...&response_type=code&code_challenge=...&redirect_uri=...
POST /token (exchange code for tokens)
GET /userinfo (get user info with access token)

Pattern 2: Service-to-Service Token

Steps: 1. Authenticate with client credentials 2. Receive access token 3. Use token for service-to-service API calls

Example Flow: 

POST /token
{
  "grant_type": "client_credentials",
  "client_id": "...",
  "client_secret": "..."
}

Authorization: Bearer {access_token}
GET /api/...

Pattern 3: User Registration and Management

Steps: 1. Register new user 2. Verify email 3. Update user profile 4. Assign roles

Example Flow: 

POST /users
{
  "email": "user@example.com",
  "password": "...",
  "tenantId": "tenant-123"
}

POST /users/{userId}/verify-email
PUT /users/{userId}/profile
POST /users/{userId}/roles

Pattern 4: Federated Login

Steps: 1. Redirect user to the Authorization Server 2. Authorization Server challenges the configured external IdP 3. External IdP returns a signed assertion or authorization response 4. Identity Backend links or provisions the local account according to tenant policy 5. Authorization Server issues ConnectSoft tokens with normalized claims

Pattern 5: MFA Step-Up

Steps: 1. User attempts a privileged action 2. API or gateway policy requires an elevated authentication context 3. Client redirects to an MFA challenge 4. Identity Backend verifies the factor 5. Authorization Server issues or refreshes tokens with the required assurance claim

Error Handling and Status Codes

Standard HTTP Status Codes

  • 200 OK - Successful request
  • 201 Created - Resource created successfully
  • 400 Bad Request - Invalid request (e.g., invalid grant type)
  • 401 Unauthorized - Authentication required or invalid token
  • 403 Forbidden - Insufficient permissions
  • 404 Not Found - Resource not found
  • 409 Conflict - Resource conflict (e.g., user already exists)
  • 500 Internal Server Error - Server error
  • 503 Service Unavailable - Service temporarily unavailable

OAuth2 Error Responses

{
  "error": "invalid_grant",
  "error_description": "The authorization code has expired",
  "error_uri": "https://identity.connectsoft.io/docs/errors/invalid_grant"
}

Versioning and Compatibility

API Versioning

  • URL Versioning - /api/v1/, /api/v2/, etc.
  • OAuth2/OIDC Standards - Follows OAuth2/OIDC specification versions
  • Backward Compatibility - Maintain backward compatibility within major versions

Compatibility

  • OAuth2 2.0 - Full OAuth2 2.0 compliance
  • OpenID Connect 1.0 - Full OIDC 1.0 compliance
  • Token Format - JWT tokens (RFC 7519)
  • JWKS Endpoint - /jwks for public key discovery
  • Flow Compatibility - New clients must use authorization code with PKCE or client credentials; implicit and password grants are not ConnectSoft defaults

Tip

Best Practices: 1. Use standard OAuth2/OIDC libraries 2. Validate tokens before use 3. Handle token refresh automatically 4. Respect token expiration 5. Use HTTPS for all API calls