---
title: "IP Address API"
description: "IP Address API endpoint documentation for retrieving client IP addresses. Get IPv4 and IPv6 addresses with a simple REST API call for IP detection and geolocation services."
keywords: "ip address api, get ip address, client ip api, ipv4 api, ipv6 api, ip detection api, what is my ip api, public ip api, ip lookup api, rest ip api"

robots: index, follow
permalink: /docs/api-reference/ip-api/

order: 3
category: API Reference

layout: docs.html
---

# IP Address API

The IP Address API returns the client's IPv4 and/or IPv6 address. This is a public endpoint that requires no authentication.

## Endpoint

```
https://api.autheona.com/v1/public/ip
```

## Method

```
POST
```

## Authentication

This endpoint does not require authentication. No access token is needed.

## Request Headers

```
Content-Type: application/json
```

## Rate Limits

Rate limits are enforced per IP address:

- **Limit**: 10 requests per second
- **Window**: 1 second

If you exceed the rate limit, implement exponential backoff in your integration.

## Request Parameters

This endpoint accepts no request parameters. Simply send a POST request to retrieve your IP address.

## Response

### Success Response (HTTP 200)

```json
{
  "ipv4_address": "203.0.113.42",
  "ipv6_address": "2001:0db8:85a3:0000:0000:8a2e:0370:7334"
}
```

### Response Fields

| Field | Type | Description |
|-------|------|-------------|
| `ipv4_address` | string or null | The client's IPv4 address. Returns `null` if the request was made over IPv6 only. |
| `ipv6_address` | string or null | The client's IPv6 address. Returns `null` if the request was made over IPv4 only. |

## Examples

### Basic Request (IPv4)

```bash
curl -X POST https://api.autheona.com/v1/public/ip \
  -H "Content-Type: application/json"
```

**Response:**

```json
{
  "ipv4_address": "203.0.113.42",
  "ipv6_address": null
}
```

### Basic Request (IPv6)

```bash
curl -X POST https://api.autheona.com/v1/public/ip \
  -H "Content-Type: application/json"
```

**Response:**

```json
{
  "ipv4_address": null,
  "ipv6_address": "2001:0db8:85a3:0000:0000:8a2e:0370:7334"
}
```

### Dual Stack (IPv4 and IPv6)

```bash
curl -X POST https://api.autheona.com/v1/public/ip \
  -H "Content-Type: application/json"
```

**Response:**

```json
{
  "ipv4_address": "203.0.113.42",
  "ipv6_address": "2001:0db8:85a3:0000:0000:8a2e:0370:7334"
}
```

## Error Responses

### Too Many Requests (HTTP 429)

Returned when rate limit is exceeded:

```json
{
  "code": 429,
  "error": "Rate limit exceeded",
  "status": false
}
```

### Internal Server Error (HTTP 500)

Returned when an unexpected error occurs:

```json
{
  "code": 500,
  "error": "Error message describing what went wrong",
  "id": "a7db4e2b-7bc1-4a82-bc19-4ff6a2e7f778",
  "status": false
}
```

The `id` field contains a unique identifier for tracking the error.

## Best Practices

- **Cache results** - Cache the IP address response for a short period (e.g., 5 minutes) to reduce API calls
- **Handle dual stack** - Check both `ipv4_address` and `ipv6_address` fields as either may be null
- **Respect rate limits** - Implement exponential backoff if you receive rate limit errors
- **Privacy considerations** - Handle IP addresses in compliance with privacy regulations (GDPR, CCPA, etc.)
- **Use HTTPS** - Always use HTTPS to protect IP address data in transit

## Integration Example

```javascript
async function getClientIP() {
  try {
    const response = await fetch('https://api.autheona.com/v1/public/ip', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      }
    });

    const data = await response.json();
    return data.ipv4_address || data.ipv6_address;
  } catch (error) {
    console.error('Failed to retrieve IP:', error);
    return null;
  }
}
```

## Response Time

Average response time is under 50ms. Response time may vary based on:

- Network latency
- Geographic distance from API servers
- Current server load