Basic Authentication Policy
General Information
Policy Type
policy-auth-basic
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)
{
"status": "SUCCESS",
"resultList": [
{
"apiProxy": {
"name": "MyAPI",
"requestPolicyList": [
{
"type": "policy-auth-basic",
"name": "basic-auth-policy",
"description": "Basic authentication policy",
"active": true,
"usernameVar": {
"type": "HEADER",
"headerName": "Authorization"
},
"clearAuth": false,
"addUserToHeader": true,
"userHeaderName": "X-Authenticated-User"
}
],
"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
{
"operationMetadata": {
"targetScope": "ALL",
"targetPipeline": "REQUEST",
"deploy": true,
"deployTargetEnvironmentNameList": ["production"],
"order": 1
},
"policy": {
"type": "policy-auth-basic",
"description": "Basic authentication policy - validate credentials from Authorization header",
"active": true,
"usernameVar": {
"type": "HEADER",
"headerName": "Authorization"
},
"clearAuth": false,
"addUserToHeader": true,
"userHeaderName": "X-Authenticated-User"
}
}
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 endpointsENDPOINT- Policy applies only to specified endpoint
Enum: targetPipeline
REQUEST- Executes in request pipelineRESPONSE- Executes in response pipelineERROR- 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-basic |
| description | string | No | - | Policy description |
| active | boolean | No | true | Whether policy is active |
| usernameVar | object | Yes | - | Variable to extract username from request (Base64 Basic Auth) |
| clearAuth | boolean | No | false | Clear authentication header after validation |
| addUserToHeader | boolean | No | false | Add authenticated user to header |
| userHeaderName | string | No* | - | Header name to add authenticated user (required if addUserToHeader=true) |
| validateACLForIssuer | boolean | No | true | Validate the Consumer's access list (ACL) for this API Proxy or Proxy Group. Applies when the identity source is Secret Manager. |
validateACLForIssuer: Optional, defaults totruewhen omitted. Whenfalse, the policy runs in identity-only mode: it still resolves and verifies the identity, but does not check the Consumer's access list (ACL) for this API Proxy or Proxy Group. Every active Consumer that passes the identity rules can then call the API. It has no effect with LDAP, Database, API or OIDC identity sources, which never consult the ACL. Same field name aspolicy-auth-mtls.
Note: userHeaderName is required when addUserToHeader is true.
usernameVar
| Field | Type | Required | Description |
|---|---|---|---|
| type | string | Yes | Variable type: HEADER, PARAMETER, BODY, CONTEXT_VALUES, CUSTOM |
| headerName | string | No* | Header name (required if type=HEADER) |
| paramName | string | No* | Parameter name (required if type=PARAMETER) |
| contextValue | string | No* | Context value (required if type=CONTEXT_VALUES) |
type
HEADER- Extract from HTTP header (typically "Authorization")PARAMETER- Extract from query/path parameterBODY- Extract from request bodyCONTEXT_VALUES- Extract from system context values (e.g.,REQUEST_REMOTE_ADDRESSfor the client IP)CUSTOM- Custom variable defined with a script
contextValue
REQUEST_REMOTE_ADDRESS- Client IP addressREQUEST_XFORWARDED_FOR- X-Forwarded-For header valueREQUEST_REQUEST_URI- Request URIREQUEST_PATH_INFO- Request pathREQUEST_HTTP_METHOD- HTTP method
The full list is on Variable Definition.
Basic Authentication Format
The Authorization header should contain: Basic <base64(username:password)>
Example: Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Response
Success Response (200 OK)
{
"status": "SUCCESS",
"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/basic-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-basic",
"description": "Basic authentication policy",
"active": true,
"usernameVar": {
"type": "HEADER",
"headerName": "Authorization"
},
"clearAuth": false,
"addUserToHeader": true,
"userHeaderName": "X-Authenticated-User"
}
}'
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"],
"order": 1
},
"policy": {
"type": "policy-auth-basic",
"description": "Updated basic authentication policy",
"active": true,
"usernameVar": {
"type": "HEADER",
"headerName": "Authorization"
},
"clearAuth": true,
"addUserToHeader": true,
"userHeaderName": "X-User"
}
}
Note: Request body structure is the same as Add Policy. All fields should be provided for update.
Response
Success Response (200 OK)
{
"status": "SUCCESS",
"deploymentResult": {
"success": true,
"deploymentResults": [
{
"environmentName": "production",
"success": true,
"message": "Deployment successful"
}
]
}
}
cURL Example
curl -X PUT \
"https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/policies/basic-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-basic",
"description": "Updated basic authentication policy",
"active": true,
"usernameVar": {
"type": "HEADER",
"headerName": "Authorization"
},
"clearAuth": true,
"addUserToHeader": true,
"userHeaderName": "X-User"
}
}'
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
}
}
Request Body Fields
operationMetadata
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| targetScope | string | Yes | - | Policy scope: ALL or ENDPOINT |
| targetPipeline | string | Yes | - | Pipeline: REQUEST, RESPONSE, or ERROR |
| deploy | boolean | No | false | Whether to deploy after deletion |
Response
Success Response (200 OK)
{
"status": "SUCCESS",
"deploymentResult": {
"success": true,
"deploymentResults": []
}
}
cURL Example
curl -X DELETE \
"https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/policies/basic-auth-policy/" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"operationMetadata": {
"targetScope": "ALL",
"targetPipeline": "REQUEST",
"deploy": false
}
}'
Notes and Warnings
-
Authentication Source: This policy validates credentials against an authentication source configured in the policy (LDAP, Database, Memory, or API). Configure the authentication source separately.
-
Authorization Header: Standard Basic Authentication uses the
Authorizationheader with format:Basic <base64(username:password)> -
Base64 Encoding: Credentials are Base64 encoded as
base64(username:password) -
Clear Auth: When
clearAuth: true, the Authorization header is removed after validation (prevents forwarding credentials to backend) -
Add User to Header: When
addUserToHeader: true, the authenticated username is added to the specified header -
User Header Name: Required when
addUserToHeader: true. This header will contain the authenticated username. -
Variable Extraction: The
usernameVarextracts the Base64 encoded credentials. The policy decodes and validates them. -
Deployment: Policy changes require deployment to take effect. Set
deploy: trueor deploy manually.
Related Documentation
- List Policies - List all policies
- Add Policy - General policy addition guide
- Update Policy - General policy update guide
- Delete Policy - General policy deletion guide