mTLS Authentication Policy

General Information

Policy Type

policy-auth-mtls

UI Documentation

📖 For detailed information: [UI Documentation Link - Link will be added here]

Description

mTLS (Mutual TLS) Authentication policy authenticates clients using X.509 certificates. It validates client certificates presented during TLS handshake and optionally validates certificate issuer ACL (Access Control List). This policy provides strong authentication based on PKI (Public Key Infrastructure).

Endpoints

List Policies

GET /apiops/projects/{projectName}/apiProxies/{apiProxyName}/policies/

Add Policy

POST /apiops/projects/{projectName}/apiProxies/{apiProxyName}/policies/{policyName}/

Update Policy

PUT /apiops/projects/{projectName}/apiProxies/{apiProxyName}/policies/{policyName}/

Delete Policy

DELETE /apiops/projects/{projectName}/apiProxies/{apiProxyName}/policies/{policyName}/

List Policies

Endpoint

GET /apiops/projects/{projectName}/apiProxies/{apiProxyName}/policies/

Request

Headers

Header Value
Authorization Bearer {token}

Path Parameters

Parameter Type Required Description
projectName string Yes Project name
apiProxyName string Yes API Proxy name

Response

Success Response (200 OK)

{
  "success": true,
  "resultList": [
    {
      "apiProxy": {
        "name": "MyAPI",
        "requestPolicyList": [
          {
            "type": "policy-auth-mtls",
            "name": "mtls-auth-policy",
            "description": "Authenticate clients using mTLS",
            "active": true,
            "validateCertificate": true,
            "validateACLForIssuer": true
          }
        ],
        "responsePolicyList": [],
        "errorPolicyList": []
      }
    }
  ],
  "resultCount": 1
}

cURL Example

curl -X GET \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/policies/" \
  -H "Authorization: Bearer YOUR_TOKEN"

Add Policy

Endpoint

POST /apiops/projects/{projectName}/apiProxies/{apiProxyName}/policies/{policyName}/

Request

Headers

Header Value
Authorization Bearer {token}
Content-Type application/json

Path Parameters

Parameter Type Required Description
projectName string Yes Project name
apiProxyName string Yes API Proxy name
policyName string Yes Policy name

Request Body

Full JSON Body Example - Full Validation
{
  "operationMetadata": {
    "targetScope": "ALL",
    "targetPipeline": "REQUEST",
    "deploy": true,
    "deployTargetEnvironmentNameList": ["production"],
    "order": 1
  },
  "policy": {
    "type": "policy-auth-mtls",
    "description": "mTLS authentication with full validation",
    "active": true,
    "validateCertificate": true,
    "validateACLForIssuer": true
  }
}
Full JSON Body Example - Certificate Validation Only
{
  "operationMetadata": {
    "targetScope": "ALL",
    "targetPipeline": "REQUEST",
    "deploy": true,
    "deployTargetEnvironmentNameList": ["production"],
    "order": 1
  },
  "policy": {
    "type": "policy-auth-mtls",
    "description": "mTLS authentication with certificate validation only",
    "active": true,
    "validateCertificate": true,
    "validateACLForIssuer": false
  }
}
Request Body Fields
operationMetadata
Field Type Required Default Description
targetScope string Yes - Policy scope: ALL or ENDPOINT
targetEndpoint string No* - Endpoint path (required if targetScope=ENDPOINT)
targetEndpointHTTPMethod string No* - HTTP method (required if targetScope=ENDPOINT)
targetPipeline string Yes - Pipeline: REQUEST, RESPONSE, or ERROR
deploy boolean No true Whether to deploy after adding policy
deployTargetEnvironmentNameList array No [] List of environment names to deploy to
order integer No null Policy execution order (starts from 1)

Enum: targetScope

  • ALL - Policy applies to all endpoints
  • ENDPOINT - Policy applies only to specified endpoint

Enum: targetPipeline

  • REQUEST - Executes in request pipeline (authenticates request)
  • RESPONSE - Executes in response pipeline
  • ERROR - Executes in error pipeline

Enum: targetEndpointHTTPMethod

  • GET, POST, PUT, DELETE, PATCH, OPTIONS, HEAD
policy
Field Type Required Default Description
type string Yes - Policy type: policy-auth-mtls
description string No - Policy description
active boolean No true Whether policy is active
validateCertificate boolean No true Validate client certificate
validateACLForIssuer boolean No true Validate ACL for certificate issuer

Note

  • validateCertificate: When true, validates client certificate (signature, expiration, chain).
  • validateACLForIssuer: When true, validates that certificate issuer is in the allowed ACL list.
  • Both validations are enabled by default for maximum security.

Response

Success Response (200 OK)

{
  "success": true,
  "deploymentResult": {
    "success": true,
    "deploymentResults": [
      {
        "environmentName": "production",
        "success": true,
        "message": "Deployment successful"
      }
    ]
  }
}

cURL Example

curl -X POST \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/policies/mtls-auth-policy/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operationMetadata": {
      "targetScope": "ALL",
      "targetPipeline": "REQUEST",
      "deploy": true,
      "deployTargetEnvironmentNameList": ["production"],
      "order": 1
    },
    "policy": {
      "type": "policy-auth-mtls",
      "description": "mTLS authentication",
      "active": true,
      "validateCertificate": true,
      "validateACLForIssuer": true
    }
  }'

Update Policy

Endpoint

PUT /apiops/projects/{projectName}/apiProxies/{apiProxyName}/policies/{policyName}/

Request

Headers

Header Value
Authorization Bearer {token}
Content-Type application/json

Path Parameters

Parameter Type Required Description
projectName string Yes Project name
apiProxyName string Yes API Proxy name
policyName string Yes Policy name

Request Body

Full JSON Body Example
{
  "operationMetadata": {
    "targetScope": "ALL",
    "targetPipeline": "REQUEST",
    "deploy": true,
    "deployTargetEnvironmentNameList": ["production", "staging"],
    "order": 1
  },
  "policy": {
    "type": "policy-auth-mtls",
    "description": "Updated: mTLS authentication with enhanced certificate validation",
    "active": true,
    "validateCertificate": true,
    "validateACLForIssuer": true
  }
}

Note: Request body structure is the same as Add Policy. All fields should be provided for update.

Response

Success Response (200 OK)

{
  "success": true,
  "deploymentResult": {
    "success": true,
    "deploymentResults": [
      {
        "environmentName": "production",
        "success": true,
        "message": "Deployment successful"
      }
    ]
  }
}

Delete Policy

Endpoint

DELETE /apiops/projects/{projectName}/apiProxies/{apiProxyName}/policies/{policyName}/

Request

Headers

Header Value
Authorization Bearer {token}
Content-Type application/json

Path Parameters

Parameter Type Required Description
projectName string Yes Project name
apiProxyName string Yes API Proxy name
policyName string Yes Policy name

Request Body

Full JSON Body Example
{
  "operationMetadata": {
    "targetScope": "ALL",
    "targetPipeline": "REQUEST",
    "deploy": false
  }
}

Response

Success Response (200 OK)

{
  "success": true,
  "deploymentResult": {
    "success": true,
    "deploymentResults": []
  }
}

Notes and Warnings

  • Certificate Validation:
    • When validateCertificate: true, validates certificate signature, expiration, and certificate chain
    • Certificate must be valid and not expired
    • Certificate chain must be trusted
  • Issuer ACL Validation:
    • When validateACLForIssuer: true, validates that certificate issuer is in the allowed ACL list
    • ACL must be configured separately in Apinizer
    • Only certificates from allowed issuers are accepted
  • TLS Configuration:
    • mTLS requires TLS to be enabled on the API Proxy
    • Client certificates must be presented during TLS handshake
    • Server must request client certificate during handshake
  • Certificate Format:
    • Supports X.509 certificates (PEM, DER formats)
    • Certificate must include public key and signature
    • Certificate chain validation requires intermediate and root CA certificates
  • Security:
    • mTLS provides strong authentication based on PKI
    • More secure than password-based authentication
    • Requires proper certificate management
  • Performance: Certificate validation adds minimal overhead to TLS handshake
  • Pipeline:
    • REQUEST pipeline validates client certificate before processing request
    • Authentication failure results in 401 Unauthorized response
  • Error Handling: Invalid or missing certificates cause authentication to fail
  • Deployment: Policy changes require deployment to take effect. Set deploy: true or deploy manually.