> ## Documentation Index
> Fetch the complete documentation index at: https://docs.avraapi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Check VPN, proxy, and IP risk
> Classify one permitted IPv4 or IPv6 address for VPN, proxy, Tor, relay, and hosting signals.
Use this endpoint when your application needs IP-risk signals during a sign-up, login, or abuse-prevention decision. It accepts one permitted IPv4 or IPv6 address and returns a normalised result, regardless of which configured Security provider produced it.
**Live Testing Guide:** Before using **Try it**, create a Development project, then enter its **Client ID** and **Client Secret**. Configure the relevant provider for that project before sending the request.
## API endpoint
```text title="POST" theme={null}
https://avraapi.com/api/v1/security/vpn-shield
```
## Request fields
| Field | Required | Rules |
| - | - | - |
| `ip` | Yes | A valid IPv4 or IPv6 address. |
Outside the documentation Playground, keep the Project Client Secret on your backend. Do not call this endpoint directly from browser code, and process only IP addresses that you are permitted to use for your security workflow.
## Result fields
| Field | Type | Notes |
| - | - | - |
| `ip_address` | string | The IP address evaluated by the service. |
| `is_vpn` | boolean | Whether the provider classified the address as a VPN. |
| `is_proxy` | boolean | Whether the provider classified the address as a proxy. |
| `is_tor` | boolean | Whether the provider classified the address as a Tor exit node. |
| `is_relay` | boolean | Whether the provider classified the address as a relay. |
| `is_hosting` | boolean | Whether the provider classified the address as hosting or data-centre infrastructure. |
| `country_code` | string or `null` | Provider-reported country code, when available. |
| `city` | string or `null` | Provider-reported city, when available. |
| `asn` | string or `null` | Provider-reported autonomous-system number, when available. |
| `network_name` | string or `null` | Provider-reported network or organisation name, when available. |
| `provider_name` | string | The AvraAPI Security provider that produced the normalised result. |
A `false` risk signal means the selected provider did not classify the address for that indicator. Combine these signals with your own risk policy; they are not a standalone decision to block or approve a user.
## Request example
This example uses IPv4. The same field also accepts a valid IPv6 address, such as `2001:4860:4860::8888`.
```bash curl theme={null} theme={null}
curl --request POST "https://avraapi.com/api/v1/security/vpn-shield" \
--header "X-API-KEY: YOUR_PROJECT_CLIENT_ID" \
--header "X-API-SECRET: YOUR_PROJECT_CLIENT_SECRET" \
--header "X-ENV: development" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data '{"ip":"203.0.113.10"}'
```
## Response example
```json theme={null}
{
"success": true,
"request_id": "1fa95b0c-f0da-4b07-9b1d-5235aca6ca20",
"data": {
"ip_address": "194.195.93.1",
"is_vpn": true,
"is_proxy": false,
"is_tor": false,
"is_relay": false,
"is_hosting": true,
"country_code": "US",
"city": "San Jose",
"asn": "AS212238",
"network_name": "Datacamp Limited",
"provider_name": "iplocate"
}
}
```
## Error codes
| HTTP | `error.code` | When it happens | What to do |
| - | - | - | - |
| `401` | unauthorized | Credentials are missing, invalid, inactive, or do not match the selected environment. | Check your backend secret configuration and `X-ENV`. |
| `402` | insufficient\_funds | The selected Security integration requires credits that are unavailable. | Check the project's current service configuration and balance. |
| `422` | validation\_failed | `ip` is missing or is not valid IPv4/IPv6 text. The response includes field details. | Correct the request field and submit a new request. |
| `422` | provider\_selection\_failed | The required Security provider is unavailable for the project environment. | Enable or configure the provider for the selected environment. |
| `429` | rate\_limit\_exceeded | The configured request limit was reached. | Respect `Retry-After` when present; do not retry in a tight loop. |
| `500` | internal\_error | The service could not complete an unexpected failure. | Retry only if your workflow permits it, retaining the request ID. |
| `503` | service\_unavailable | Available upstream VPN-intelligence providers could not complete the lookup. | Retry later with the same risk workflow; do not treat an unavailable check as a safe result. |
| `503` | project\_paused | The project is paused. | Reactivate the project before retrying. |
Keep the JSON `request_id` or `X-APIX-Request-ID` response header with your support record. It is the safest way for AvraAPI support to trace a request.
See the [REST API guide](/api-reference/rest-api) for shared credential, privacy, and error-handling guidance.
## Playground resources
The generated reference below lists this endpoint's API standard details: request fields, authorizations, and response schema. The complete integration guide, request and response examples, and endpoint-specific error handling are above.
## OpenAPI
````yaml api-reference/provider-api.openapi.yaml POST /security/vpn-shield
openapi: 3.0.3
info:
title: AvraAPI Provider API
version: 1.0.0
description: >-
The reviewed public contract for AvraAPI provider services. Operations are
added to this document only after their route, validation, response,
privacy, usage, and public-safety contracts have been verified.
servers:
- url: https://avraapi.com/api/v1
description: AvraAPI REST API v1
security:
- ApiKeyHeader: []
ApiSecretHeader: []
tags:
- name: Currency
description: Currency codes, exchange rates, and conversion.
- name: SMS
description: Messaging operations through configured AvraAPI providers.
- name: Security
description: IP and email security checks.
- name: Location
description: IP geolocation and intelligence.
- name: Utilities
description: QR code, barcode, and PDF generation.
paths:
/security/vpn-shield:
post:
tags:
- Security
summary: Check VPN, proxy, and IP risk
description: >-
Classifies one permitted IPv4 or IPv6 address for VPN, proxy, Tor,
relay, and hosting signals. AvraAPI normalises the response from the
configured Security provider. Treat these signals as input to your own
risk policy, not as an automatic allow or deny decision.
operationId: checkVpnShield
parameters:
- $ref: '#/components/parameters/XEnvironmentHeader'
- $ref: '#/components/parameters/AcceptJsonHeader'
- $ref: '#/components/parameters/XPrivacyModeHeader'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/VpnShieldRequest'
examples:
ipv4:
summary: Documentation-only TEST-NET IPv4 address
value:
ip: 203.0.113.10
ipv6:
summary: Documentation-only IPv6 address
value:
ip: 2001:db8::10
responses:
'200':
description: Normalised VPN and proxy risk result.
headers:
X-APIX-Request-ID:
$ref: '#/components/headers/RequestIdHeader'
content:
application/json:
schema:
$ref: '#/components/schemas/VpnShieldResponse'
examples:
classified_ip:
summary: Provider-classified IPv4 address
value:
success: true
request_id: 1fa95b0c-f0da-4b07-9b1d-5235aca6ca20
data:
ip_address: 194.195.93.1
is_vpn: true
is_proxy: false
is_tor: false
is_relay: false
is_hosting: true
country_code: US
city: San Jose
asn: AS212238
network_name: Datacamp Limited
provider_name: iplocate
'401':
description: >-
Missing, invalid, inactive, or environment-mismatched project
credentials.
headers:
X-APIX-Request-ID:
$ref: '#/components/headers/RequestIdHeader'
content:
application/json:
schema:
$ref: '#/components/schemas/SecurityUnauthorizedErrorEnvelope'
examples:
unauthorized:
value:
success: false
request_id: 3c90c3cc-0d44-4b50-8888-8dd25736052a
error:
code: unauthorized
message:
details: {}
meta: {}
'402':
description: >-
The selected Security integration requires credits that are
unavailable.
headers:
X-APIX-Request-ID:
$ref: '#/components/headers/RequestIdHeader'
content:
application/json:
schema:
$ref: '#/components/schemas/SecurityInsufficientFundsErrorEnvelope'
examples:
insufficient_funds:
value:
success: false
request_id: 3c90c3cc-0d44-4b50-8888-8dd25736052a
error:
code: insufficient_funds
message:
details: {}
meta: {}
'422':
description: >-
Invalid request fields. See the Error codes table for the separate
provider-selection outcome.
headers:
X-APIX-Request-ID:
$ref: '#/components/headers/RequestIdHeader'
content:
application/json:
schema:
$ref: '#/components/schemas/SecurityValidationErrorEnvelope'
examples:
validation_failed:
value:
success: false
request_id: 3c90c3cc-0d44-4b50-8888-8dd25736052a
error:
code: validation_failed
message:
details: {}
meta: {}
'429':
description: The configured Security request limit has been reached.
headers:
X-APIX-Request-ID:
$ref: '#/components/headers/RequestIdHeader'
Retry-After:
$ref: '#/components/headers/RetryAfterHeader'
content:
application/json:
schema:
$ref: '#/components/schemas/SecurityRateLimitedErrorEnvelope'
examples:
rate_limit_exceeded:
value:
success: false
request_id: 3c90c3cc-0d44-4b50-8888-8dd25736052a
error:
code: rate_limit_exceeded
message:
details: {}
meta: {}
'500':
description: The Security service could not complete the request.
headers:
X-APIX-Request-ID:
$ref: '#/components/headers/RequestIdHeader'
content:
application/json:
schema:
$ref: '#/components/schemas/SecurityInternalErrorEnvelope'
examples:
internal_error:
value:
success: false
request_id: 3c90c3cc-0d44-4b50-8888-8dd25736052a
error:
code: internal_error
message:
details: {}
meta: {}
'503':
description: >-
Available upstream VPN-intelligence providers could not complete the
lookup.
headers:
X-APIX-Request-ID:
$ref: '#/components/headers/RequestIdHeader'
content:
application/json:
schema:
$ref: '#/components/schemas/VpnShieldServiceUnavailableErrorEnvelope'
examples:
service_unavailable:
value:
success: false
request_id: 3c90c3cc-0d44-4b50-8888-8dd25736052a
error:
code: service_unavailable
message:
details: {}
meta: {}
components:
parameters:
XEnvironmentHeader:
name: X-ENV
in: header
required: false
description: >-
Selects the Development credential environment. The Documentation
Playground exposes Development values only; normal backend integrations
may use their documented Production credentials outside this tool.
schema:
type: string
enum:
- dev
- development
default: development
AcceptJsonHeader:
name: Accept
in: header
required: false
description: Requests a JSON response where the selected operation supports JSON.
schema:
type: string
example: application/json
XPrivacyModeHeader:
name: X-Privacy-Mode
in: header
required: false
description: >-
Optional privacy override. Turn this on to request that AvraAPI suppress
request-payload storage in observability logs for this request.
schema:
type: boolean
default: false
example: true
schemas:
VpnShieldRequest:
type: object
required:
- ip
properties:
ip:
type: string
format: ip
description: A valid IPv4 or IPv6 address.
example: 203.0.113.10
VpnShieldResponse:
allOf:
- $ref: '#/components/schemas/ApiSuccessEnvelope'
- type: object
properties:
data:
$ref: '#/components/schemas/VpnShieldData'
SecurityUnauthorizedErrorEnvelope:
type: object
required:
- success
- request_id
- error
properties:
success:
type: boolean
enum:
- false
request_id:
type: string
format: uuid
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- unauthorized
example: unauthorized
message:
type: string
details:
type: object
additionalProperties: true
meta:
type: object
additionalProperties: true
SecurityInsufficientFundsErrorEnvelope:
type: object
required:
- success
- request_id
- error
properties:
success:
type: boolean
enum:
- false
request_id:
type: string
format: uuid
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- insufficient_funds
example: insufficient_funds
message:
type: string
details:
type: object
additionalProperties: true
meta:
type: object
additionalProperties: true
SecurityValidationErrorEnvelope:
type: object
required:
- success
- request_id
- error
properties:
success:
type: boolean
enum:
- false
request_id:
type: string
format: uuid
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- validation_failed
example: validation_failed
message:
type: string
details:
type: object
additionalProperties: true
meta:
type: object
additionalProperties: true
SecurityRateLimitedErrorEnvelope:
type: object
required:
- success
- request_id
- error
properties:
success:
type: boolean
enum:
- false
request_id:
type: string
format: uuid
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- rate_limit_exceeded
example: rate_limit_exceeded
message:
type: string
details:
type: object
additionalProperties: true
meta:
type: object
additionalProperties: true
SecurityInternalErrorEnvelope:
type: object
required:
- success
- request_id
- error
properties:
success:
type: boolean
enum:
- false
request_id:
type: string
format: uuid
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- internal_error
example: internal_error
message:
type: string
details:
type: object
additionalProperties: true
meta:
type: object
additionalProperties: true
VpnShieldServiceUnavailableErrorEnvelope:
type: object
required:
- success
- request_id
- error
properties:
success:
type: boolean
enum:
- false
request_id:
type: string
format: uuid
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- service_unavailable
example: service_unavailable
message:
type: string
details:
type: object
additionalProperties: true
meta:
type: object
additionalProperties: true
ApiSuccessEnvelope:
type: object
required:
- success
- request_id
- data
properties:
success:
type: boolean
enum:
- true
request_id:
type: string
format: uuid
description: Include this value when contacting AvraAPI support.
data:
description: Operation-specific result data.
nullable: true
VpnShieldData:
type: object
required:
- ip_address
- is_vpn
- is_proxy
- is_tor
- is_relay
- is_hosting
- country_code
- city
- asn
- network_name
- provider_name
properties:
ip_address:
type: string
format: ip
description: The evaluated IP address.
is_vpn:
type: boolean
description: Whether the provider classified the address as a VPN.
is_proxy:
type: boolean
description: Whether the provider classified the address as a proxy.
is_tor:
type: boolean
description: Whether the provider classified the address as a Tor exit node.
is_relay:
type: boolean
description: Whether the provider classified the address as a relay.
is_hosting:
type: boolean
description: >-
Whether the provider classified the address as hosting
infrastructure.
country_code:
type: string
nullable: true
description: Provider-reported country code, when available.
city:
type: string
nullable: true
description: Provider-reported city, when available.
asn:
type: string
nullable: true
description: Provider-reported autonomous-system number, when available.
network_name:
type: string
nullable: true
description: Provider-reported network or organisation name, when available.
provider_name:
type: string
description: The Security provider that produced the normalised result.
headers:
RequestIdHeader:
description: AvraAPI request identifier for support and troubleshooting.
schema:
type: string
format: uuid
RetryAfterHeader:
description: Seconds to wait before retrying a rate-limited request.
schema:
type: integer
minimum: 0
securitySchemes:
ApiKeyHeader:
type: apiKey
in: header
name: X-API-KEY
description: >-
Your Development project's Client ID. Enter your own value in the
Documentation Playground.
ApiSecretHeader:
type: apiKey
in: header
name: X-API-SECRET
description: >-
Your Development project's Client Secret. Mintlify does not proxy these
requests; the browser sends them directly to AvraAPI. Never enter a
Production secret in the Documentation Playground.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.