Skip to content

Identity Platform API Overview

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

The Identity Platform provides a complete OpenID Connect / OAuth2 authorization server with multi-tenant support, external IdP federation, and comprehensive user management. This is a conceptual overview—concrete OpenAPI/Swagger documentation lives in the Identity Platform product repository.

Note

This is a conceptual overview of the Identity Platform API. Concrete OpenAPI/Swagger documentation with exact endpoints, request/response schemas, and authentication details lives in the Identity Platform product repository.

API Surface at a Glance

The Identity Platform API provides endpoints for:

  • Authentication - OAuth2/OIDC token endpoints
  • User Management - User registration, profile management
  • Tenant Management - Tenant creation and configuration
  • Role & Permission Management - RBAC configuration
  • External IdP Federation - External identity provider integration
  • Token Management - Token validation, introspection, revocation

Authentication and Authorization

OAuth2/OIDC Flows

  • Authorization Code Flow - Standard OAuth2 authorization code flow
  • Client Credentials Flow - Service-to-service authentication
  • Resource Owner Password Flow - Username/password authentication (limited use)
  • Implicit Flow - Not supported (deprecated)

Token Types

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

Authentication Methods

  • OAuth2/OIDC - Standard OAuth2/OIDC flows
  • API Keys - Service API keys for programmatic access
  • Certificate-Based - Mutual TLS for high-security scenarios

Main Resource Groups

Resource Group Examples Notes
Authentication /token, /authorize, /userinfo OAuth2/OIDC standard endpoints
Users /users, /users/{id}, /users/{id}/profile User CRUD operations
Tenants /tenants, /tenants/{id}, /tenants/{id}/settings Tenant management
Roles /roles, /roles/{id}, /roles/{id}/permissions Role and permission management
External IdPs /idps, /idps/{id}, /idps/{id}/federation External identity provider management
Tokens /tokens/introspect, /tokens/revoke Token validation and management

Common Usage Patterns

Pattern 1: Login via OpenID Connect

Steps: 1. Redirect user to authorization endpoint 2. User authenticates 3. Receive authorization code 4. Exchange code for tokens 5. Use access token for API calls

Example Flow: 

GET /authorize?client_id=...&response_type=code&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

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

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