OAuth2 Authentication Policy

General Information

Policy Type

policy-auth-oauth2

UI Documentation

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

Description

OAuth2 Authentication policy manages OAuth2 token authentication. It can issue, validate, and refresh OAuth2 access tokens and refresh tokens. OAuth2 is an industry-standard protocol for authorization.

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-oauth2",
            "name": "oauth2-auth-policy",
            "description": "OAuth2 authentication policy",
            "active": true,
            "tokenNeverExpires": false,
            "tokenExpiresInAmount": 3600,
            "tokenExpiresInUnit": "SECONDS",
            "refreshTokenAllowed": true,
            "refreshTokenCount": 5,
            "refreshTokenExpiresInAmount": 86400,
            "refreshTokenExpiresInUnit": "SECONDS",
            "allowUrlParameters": false,
            "managedFromThisPolicy": true,
            "grantType": "PASSWORD",
            "deletePrevious": false
          }
        ],
        "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-oauth2",
    "description": "OAuth2 authentication policy - issue and validate tokens",
    "active": true,
    "tokenNeverExpires": false,
    "tokenExpiresInAmount": 3600,
    "tokenExpiresInUnit": "SECONDS",
    "refreshTokenAllowed": true,
    "refreshTokenCount": 5,
    "refreshTokenExpiresInAmount": 86400,
    "refreshTokenExpiresInUnit": "SECONDS",
    "allowUrlParameters": false,
    "managedFromThisPolicy": true,
    "grantType": "PASSWORD",
    "deletePrevious": 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
  • 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-oauth2
description string No - Policy description
active boolean No true Whether policy is active
tokenNeverExpires boolean No true Whether token never expires
tokenExpiresInAmount long No* - Token expiration amount (required if tokenNeverExpires=false)
tokenExpiresInUnit string No* - Token expiration unit (required if tokenNeverExpires=false)
refreshTokenAllowed boolean No false Allow refresh tokens
refreshTokenCount integer No - Maximum number of refresh tokens per user
refreshTokenExpiresInAmount long No - Refresh token expiration amount
refreshTokenExpiresInUnit string No - Refresh token expiration unit
allowUrlParameters boolean No false Allow token in URL parameters
managedFromThisPolicy boolean No true Token managed from this policy
grantType string No PASSWORD Grant type for token issuance
deletePrevious boolean No false Delete previous tokens when issuing new token

EnumTimeUnit

  • MILLI_SECONDS - Milliseconds
  • SECONDS - Seconds
  • MINUTES - Minutes
  • HOURS - Hours
  • DAYS - Days
  • WEEKS - Weeks
  • MONTHS - Months
  • YEARS - Years

EnumTimeUnit

  • MILLI_SECONDS - Milliseconds
  • SECONDS - Seconds
  • MINUTES - Minutes
  • HOURS - Hours
  • DAYS - Days
  • WEEKS - Weeks
  • MONTHS - Months
  • YEARS - Years

EnumPolicyAuthenticationGrantType

  • PASSWORD - Password grant type (username/password)
  • CLIENT_CREDENTIALS - Client credentials grant type (client_id/client_secret)

Note

  • If tokenNeverExpires: false, both tokenExpiresInAmount and tokenExpiresInUnit are required.
  • refreshTokenCount limits the number of active refresh tokens per user.
  • When deletePrevious: true, issuing a new token deletes previous tokens for the same user.

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/oauth2-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-oauth2",
      "description": "OAuth2 authentication policy",
      "active": true,
      "tokenNeverExpires": false,
      "tokenExpiresInAmount": 3600,
      "tokenExpiresInUnit": "SECONDS",
      "refreshTokenAllowed": true,
      "refreshTokenCount": 5,
      "refreshTokenExpiresInAmount": 86400,
      "refreshTokenExpiresInUnit": "SECONDS",
      "allowUrlParameters": false,
      "managedFromThisPolicy": true,
      "grantType": "PASSWORD",
      "deletePrevious": false
    }
  }'

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-oauth2",
    "description": "Updated OAuth2 authentication policy",
    "active": true,
    "tokenNeverExpires": false,
    "tokenExpiresInAmount": 7200,
    "tokenExpiresInUnit": "SECONDS",
    "refreshTokenAllowed": true,
    "refreshTokenCount": 10,
    "refreshTokenExpiresInAmount": 172800,
    "refreshTokenExpiresInUnit": "SECONDS",
    "allowUrlParameters": false,
    "managedFromThisPolicy": true,
    "grantType": "CLIENT_CREDENTIALS",
    "deletePrevious": 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"
      }
    ]
  }
}

cURL Example

curl -X PUT \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/policies/oauth2-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-oauth2",
      "description": "Updated OAuth2 authentication policy",
      "active": true,
      "tokenNeverExpires": false,
      "tokenExpiresInAmount": 7200,
      "tokenExpiresInUnit": "SECONDS",
      "refreshTokenAllowed": true,
      "refreshTokenCount": 10,
      "refreshTokenExpiresInAmount": 172800,
      "refreshTokenExpiresInUnit": "SECONDS",
      "allowUrlParameters": false,
      "managedFromThisPolicy": true,
      "grantType": "PASSWORD",
      "deletePrevious": false
    }
  }'

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 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)

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

cURL Example

curl -X DELETE \
  "https://demo.apinizer.com/apiops/projects/MyProject/apiProxies/MyAPI/policies/oauth2-auth-policy/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operationMetadata": {
      "targetScope": "ALL",
      "targetPipeline": "REQUEST",
      "deploy": false
    }
  }'

Notes and Warnings

  • Token Expiration:
    • When tokenNeverExpires: false, provide tokenExpiresInAmount and tokenExpiresInUnit
    • When tokenNeverExpires: true, tokens never expire (use with caution)
  • Refresh Tokens:
    • When refreshTokenAllowed: true, clients can refresh expired access tokens
    • refreshTokenCount limits concurrent refresh tokens per user
    • Refresh tokens have separate expiration settings
  • Grant Types:
    • PASSWORD - Username/password authentication (Resource Owner Password Credentials)
    • CLIENT_CREDENTIALS - Client ID/client secret authentication (for service-to-service)
  • Delete Previous:
    • When deletePrevious: true, issuing a new token invalidates previous tokens for the same user
    • When deletePrevious: false, multiple tokens can be active for the same user
  • URL Parameters: When allowUrlParameters: true, tokens can be passed in URL (less secure, not recommended)
  • Managed Policy: When managedFromThisPolicy: true, tokens are issued and managed by this policy
  • OAuth2 Standard: This policy implements OAuth2 specification for token management
  • Deployment: Policy changes require deployment to take effect. Set deploy: true or deploy manually.