Identity Provider Service

Manages OIDC (OpenID Connect) identity providers for the Kulpay Collection API. Identity providers handle user authentication and authorization through standard OAuth2/OIDC protocols. The system supports multiple identity providers for flexible authentication configurations.

Create Identity Provider

POST /v1/identity_providers

Creates a new identity provider configuration.

Request Body:

{
  "name": "Corporate SSO",
  "type": "oidc",
  "client_id": "kulpay-collection-app",
  "client_secret": "s3cr3t-k3y-v4lu3",
  "encryption_key": "enc_a1b2c3d4e5f6g7h8",
  "provider_url": "https://sso.example.com",
  "issuer_url": "https://sso.example.com/realms/kulpay",
  "auth_url": "https://sso.example.com/realms/kulpay/protocol/openid-connect/auth",
  "token_url": "https://sso.example.com/realms/kulpay/protocol/openid-connect/token",
  "user_info_url": "https://sso.example.com/realms/kulpay/protocol/openid-connect/userinfo",
  "scopes": "openid profile email",
  "redirect_uris": "https://app.kulpay.com/callback",
  "end_session_endpoint": "https://sso.example.com/realms/kulpay/protocol/openid-connect/logout",
  "jwks_uri": "https://sso.example.com/realms/kulpay/protocol/openid-connect/certs",
  "registration_endpoint": "https://sso.example.com/realms/kulpay/clients-registrations/openid-connect",
  "introspection_endpoint": "https://sso.example.com/realms/kulpay/protocol/openid-connect/token/introspect",
  "revocation_endpoint": "https://sso.example.com/realms/kulpay/protocol/openid-connect/revoke",
  "well_known_url": "https://sso.example.com/realms/kulpay/.well-known/openid-configuration",
  "created_by": "admin@kulpay.com",
  "created_ip": "192.168.1.10"
}

Field	Type	Required	Description
`name`	string	Yes	Provider display name
`type`	string	Yes	Provider type (e.g., `"oidc"`, `"saml"`)
`client_id`	string	Yes	OAuth2 client ID
`client_secret`	string	Yes	OAuth2 client secret
`encryption_key`	string	Yes	Key used for token encryption
`provider_url`	string	Yes	Base URL of the identity provider
`issuer_url`	string	Yes	Token issuer URL
`auth_url`	string	Yes	Authorization endpoint URL
`token_url`	string	Yes	Token endpoint URL
`user_info_url`	string	Yes	UserInfo endpoint URL
`scopes`	string	Yes	Requested scopes (space-separated)
`redirect_uris`	string	Yes	Callback URIs for OAuth2 redirects
`end_session_endpoint`	string	Yes	Logout endpoint URL
`jwks_uri`	string	Yes	JSON Web Key Set URI
`registration_endpoint`	string	Yes	Dynamic client registration endpoint
`introspection_endpoint`	string	Yes	Token introspection endpoint
`revocation_endpoint`	string	Yes	Token revocation endpoint
`well_known_url`	string	Yes	OIDC discovery URL
`created_at`	timestamp	No	Timestamp of creation (auto-generated if not provided)
`updated_at`	timestamp	No	Timestamp of last update (auto-generated if not provided)
`created_by`	string	Yes	User or system that created the record
`updated_by`	string	No	User or system that last updated the record
`created_ip`	string	Yes	IP address of the creator
`updated_ip`	string	No	IP address of the last updater

Response:

{
  "object": "idp",
  "identity_provider": {
    "id": "idp_k7Rm2xPqW9",
    "name": "Corporate SSO",
    "type": "oidc",
    "client_id": "kulpay-collection-app",
    "client_secret": "s3cr3t-k3y-v4lu3",
    "encryption_key": "enc_a1b2c3d4e5f6g7h8",
    "provider_url": "https://sso.example.com",
    "issuer_url": "https://sso.example.com/realms/kulpay",
    "auth_url": "https://sso.example.com/realms/kulpay/protocol/openid-connect/auth",
    "token_url": "https://sso.example.com/realms/kulpay/protocol/openid-connect/token",
    "user_info_url": "https://sso.example.com/realms/kulpay/protocol/openid-connect/userinfo",
    "scopes": "openid profile email",
    "redirect_uris": "https://app.kulpay.com/callback",
    "end_session_endpoint": "https://sso.example.com/realms/kulpay/protocol/openid-connect/logout",
    "jwks_uri": "https://sso.example.com/realms/kulpay/protocol/openid-connect/certs",
    "registration_endpoint": "https://sso.example.com/realms/kulpay/clients-registrations/openid-connect",
    "introspection_endpoint": "https://sso.example.com/realms/kulpay/protocol/openid-connect/token/introspect",
    "revocation_endpoint": "https://sso.example.com/realms/kulpay/protocol/openid-connect/revoke",
    "well_known_url": "https://sso.example.com/realms/kulpay/.well-known/openid-configuration",
    "created_at": "2025-08-15T09:30:00Z",
    "updated_at": "2025-08-15T09:30:00Z",
    "created_by": "admin@kulpay.com",
    "updated_by": "admin@kulpay.com",
    "created_ip": "192.168.1.10",
    "updated_ip": "192.168.1.10"
  },
  "error": null
}

Get Identity Provider

GET /v1/identity_providers/{id}

Retrieves details of a specific identity provider by its ID.

Path Parameters:

Parameter	Type	Description
`id`	string	Identity provider ID (pattern: `^idp_[a-zA-Z0-9]+$`)

Response:

{
  "object": "idp",
  "identity_provider": {
    "id": "idp_k7Rm2xPqW9",
    "name": "Corporate SSO",
    "type": "oidc",
    "client_id": "kulpay-collection-app",
    "client_secret": "s3cr3t-k3y-v4lu3",
    "encryption_key": "enc_a1b2c3d4e5f6g7h8",
    "provider_url": "https://sso.example.com",
    "issuer_url": "https://sso.example.com/realms/kulpay",
    "auth_url": "https://sso.example.com/realms/kulpay/protocol/openid-connect/auth",
    "token_url": "https://sso.example.com/realms/kulpay/protocol/openid-connect/token",
    "user_info_url": "https://sso.example.com/realms/kulpay/protocol/openid-connect/userinfo",
    "scopes": "openid profile email",
    "redirect_uris": "https://app.kulpay.com/callback",
    "end_session_endpoint": "https://sso.example.com/realms/kulpay/protocol/openid-connect/logout",
    "jwks_uri": "https://sso.example.com/realms/kulpay/protocol/openid-connect/certs",
    "registration_endpoint": "https://sso.example.com/realms/kulpay/clients-registrations/openid-connect",
    "introspection_endpoint": "https://sso.example.com/realms/kulpay/protocol/openid-connect/token/introspect",
    "revocation_endpoint": "https://sso.example.com/realms/kulpay/protocol/openid-connect/revoke",
    "well_known_url": "https://sso.example.com/realms/kulpay/.well-known/openid-configuration",
    "created_at": "2025-08-15T09:30:00Z",
    "updated_at": "2025-08-15T09:30:00Z",
    "created_by": "admin@kulpay.com",
    "updated_by": "admin@kulpay.com",
    "created_ip": "192.168.1.10",
    "updated_ip": "192.168.1.10"
  },
  "error": null
}

List Identity Providers

GET /v1/identity_providers

Lists all configured identity providers with pagination.

Query Parameters:

Parameter	Type	Default	Description
`page_size`	integer	50	Max results per page (max: 100)
`page_token`	string	-	Token for next page

Response:

{
  "object": "list",
  "data": [
    {
      "id": "idp_k7Rm2xPqW9",
      "name": "Corporate SSO",
      "type": "oidc",
      "client_id": "kulpay-collection-app",
      "client_secret": "s3cr3t-k3y-v4lu3",
      "encryption_key": "enc_a1b2c3d4e5f6g7h8",
      "provider_url": "https://sso.example.com",
      "issuer_url": "https://sso.example.com/realms/kulpay",
      "auth_url": "https://sso.example.com/realms/kulpay/protocol/openid-connect/auth",
      "token_url": "https://sso.example.com/realms/kulpay/protocol/openid-connect/token",
      "user_info_url": "https://sso.example.com/realms/kulpay/protocol/openid-connect/userinfo",
      "scopes": "openid profile email",
      "redirect_uris": "https://app.kulpay.com/callback",
      "end_session_endpoint": "https://sso.example.com/realms/kulpay/protocol/openid-connect/logout",
      "jwks_uri": "https://sso.example.com/realms/kulpay/protocol/openid-connect/certs",
      "registration_endpoint": "https://sso.example.com/realms/kulpay/clients-registrations/openid-connect",
      "introspection_endpoint": "https://sso.example.com/realms/kulpay/protocol/openid-connect/token/introspect",
      "revocation_endpoint": "https://sso.example.com/realms/kulpay/protocol/openid-connect/revoke",
      "well_known_url": "https://sso.example.com/realms/kulpay/.well-known/openid-configuration",
      "created_at": "2025-08-15T09:30:00Z",
      "updated_at": "2025-08-15T09:30:00Z",
      "created_by": "admin@kulpay.com",
      "updated_by": "admin@kulpay.com",
      "created_ip": "192.168.1.10",
      "updated_ip": "192.168.1.10"
    },
    {
      "id": "idp_nT5vLm8dQx",
      "name": "Partner Auth0",
      "type": "oidc",
      "client_id": "partner-app-client",
      "provider_url": "https://partner.auth0.com",
      "issuer_url": "https://partner.auth0.com/",
      "scopes": "openid profile email",
      "created_at": "2025-09-01T14:00:00Z",
      "updated_at": "2025-09-01T14:00:00Z",
      "created_by": "ops@kulpay.com",
      "updated_by": "ops@kulpay.com",
      "created_ip": "10.0.0.5",
      "updated_ip": "10.0.0.5"
    }
  ],
  "has_more": false,
  "next_page_token": null,
  "error": null
}

Update Identity Provider

PUT /v1/identity_providers

Updates an existing identity provider. Only provided fields are updated.

Request Body:

{
  "id": "idp_k7Rm2xPqW9",
  "name": "Corporate SSO (Updated)",
  "scopes": "openid profile email groups",
  "redirect_uris": "https://app.kulpay.com/callback,https://staging.kulpay.com/callback",
  "updated_by": "ops@kulpay.com",
  "updated_ip": "10.0.0.5"
}

Field	Type	Required	Description
`id`	string	Yes	Identity provider ID (pattern: `^idp_[a-zA-Z0-9]+$`)
`name`	string	No	Provider display name
`type`	string	No	Provider type (e.g., `"oidc"`, `"saml"`)
`client_id`	string	No	OAuth2 client ID
`client_secret`	string	No	OAuth2 client secret
`encryption_key`	string	No	Key used for token encryption
`provider_url`	string	No	Base URL of the identity provider
`issuer_url`	string	No	Token issuer URL
`auth_url`	string	No	Authorization endpoint URL
`token_url`	string	No	Token endpoint URL
`user_info_url`	string	No	UserInfo endpoint URL
`scopes`	string	No	Requested scopes (space-separated)
`redirect_uris`	string	No	Callback URIs for OAuth2 redirects
`end_session_endpoint`	string	No	Logout endpoint URL
`jwks_uri`	string	No	JSON Web Key Set URI
`registration_endpoint`	string	No	Dynamic client registration endpoint
`introspection_endpoint`	string	No	Token introspection endpoint
`revocation_endpoint`	string	No	Token revocation endpoint
`well_known_url`	string	No	OIDC discovery URL
`updated_by`	string	No	User or system performing the update
`updated_ip`	string	No	IP address of the updater

Response:

{
  "object": "idp",
  "identity_provider": {
    "id": "idp_k7Rm2xPqW9",
    "name": "Corporate SSO (Updated)",
    "type": "oidc",
    "client_id": "kulpay-collection-app",
    "client_secret": "s3cr3t-k3y-v4lu3",
    "encryption_key": "enc_a1b2c3d4e5f6g7h8",
    "provider_url": "https://sso.example.com",
    "issuer_url": "https://sso.example.com/realms/kulpay",
    "auth_url": "https://sso.example.com/realms/kulpay/protocol/openid-connect/auth",
    "token_url": "https://sso.example.com/realms/kulpay/protocol/openid-connect/token",
    "user_info_url": "https://sso.example.com/realms/kulpay/protocol/openid-connect/userinfo",
    "scopes": "openid profile email groups",
    "redirect_uris": "https://app.kulpay.com/callback,https://staging.kulpay.com/callback",
    "end_session_endpoint": "https://sso.example.com/realms/kulpay/protocol/openid-connect/logout",
    "jwks_uri": "https://sso.example.com/realms/kulpay/protocol/openid-connect/certs",
    "registration_endpoint": "https://sso.example.com/realms/kulpay/clients-registrations/openid-connect",
    "introspection_endpoint": "https://sso.example.com/realms/kulpay/protocol/openid-connect/token/introspect",
    "revocation_endpoint": "https://sso.example.com/realms/kulpay/protocol/openid-connect/revoke",
    "well_known_url": "https://sso.example.com/realms/kulpay/.well-known/openid-configuration",
    "created_at": "2025-08-15T09:30:00Z",
    "updated_at": "2025-10-20T16:45:00Z",
    "created_by": "admin@kulpay.com",
    "updated_by": "ops@kulpay.com",
    "created_ip": "192.168.1.10",
    "updated_ip": "10.0.0.5"
  },
  "error": null
}

Delete Identity Provider

DELETE /v1/identity_providers

Deletes an identity provider configuration.

Query Parameters:

Parameter	Type	Description
`id`	string	Identity provider ID (pattern: `^idp_[a-zA-Z0-9]+$`)

Response:

{
  "object": "idp",
  "error": null
}

OIDC Discovery

Identity providers that support OpenID Connect Discovery can be configured using just the well_known_url field. When a valid discovery URL is provided, the system will automatically fetch the provider's discovery document and populate the following endpoint fields:

issuer_url -- from the issuer claim
auth_url -- from authorization_endpoint
token_url -- from token_endpoint
user_info_url -- from userinfo_endpoint
jwks_uri -- from jwks_uri
end_session_endpoint -- from end_session_endpoint
registration_endpoint -- from registration_endpoint
introspection_endpoint -- from introspection_endpoint
revocation_endpoint -- from revocation_endpoint

This simplifies provider setup to a minimal configuration:

{
  "name": "Keycloak Production",
  "type": "oidc",
  "client_id": "kulpay-app",
  "client_secret": "my-client-secret",
  "encryption_key": "enc_x9y8z7w6v5u4",
  "scopes": "openid profile email",
  "redirect_uris": "https://app.kulpay.com/callback",
  "well_known_url": "https://keycloak.example.com/realms/kulpay/.well-known/openid-configuration",
  "created_by": "admin@kulpay.com",
  "created_ip": "192.168.1.10"
}

Any explicitly provided endpoint URLs will take precedence over values discovered from the well_known_url.

Supported Provider Types

The following identity provider types are commonly configured with the system:

Provider	Type Value	Discovery URL Format
Dex	`oidc`	`https://<dex-host>/.well-known/openid-configuration`
Keycloak	`oidc`	`https://<host>/realms/<realm>/.well-known/openid-configuration`
Auth0	`oidc`	`https://<tenant>.auth0.com/.well-known/openid-configuration`
Okta	`oidc`	`https://<org>.okta.com/.well-known/openid-configuration`
Azure AD	`oidc`	`https://login.microsoftonline.com/<tenant>/v2.0/.well-known/openid-configuration`
Google	`oidc`	`https://accounts.google.com/.well-known/openid-configuration`
SAML Provider	`saml`	N/A (manual endpoint configuration required)

The type field determines how the system handles authentication flows and token validation. OIDC providers use standard OAuth2/OIDC flows, while SAML providers require manual configuration of all endpoints.

Audit Fields

All identity provider operations are fully audited. Every create and update operation records the following audit information:

Field	Type	Description
`created_at`	timestamp	When the identity provider was created
`updated_at`	timestamp	When the identity provider was last modified
`created_by`	string	User or service account that created the provider
`updated_by`	string	User or service account that last modified the provider
`created_ip`	string	IP address from which the provider was created
`updated_ip`	string	IP address from which the provider was last modified

These fields are automatically maintained by the system. The created_* fields are set once during creation and remain immutable. The updated_* fields are refreshed on every modification. Audit data is useful for compliance, debugging, and security investigations -- for example, identifying which administrator changed a provider's client_secret or redirect_uris.

Create Identity Provider​

Get Identity Provider​

List Identity Providers​

Update Identity Provider​

Delete Identity Provider​

OIDC Discovery​

Supported Provider Types​

Audit Fields​

Create Identity Provider

Get Identity Provider

List Identity Providers

Update Identity Provider

Delete Identity Provider

OIDC Discovery

Supported Provider Types

Audit Fields