User Management API

The User Management API allows you to create and manage user sessions for the embedded domain interface.

Create User Session

Creates a new user session and returns a login URL for the embedded interface.

Endpoint: POST /api/v1/users

Request

POST /api/v1/users
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "user_identifier": "string",
  "email": "string" // optional
}

Parameters

Parameter	Type	Required	Description
user_identifier	string	Yes	Your unique internal user ID (max 255 chars)
email	string	No	User's email address for better UX

Constraints

• user_identifier must be unique per API key
• user_identifier can contain letters, numbers, underscores, and hyphens only
• email must be a valid email address format if provided

Response

{
  "user_identifier": "user_123",
  "login_url": "https://embed.pocketdns.com/session/abc123def456",
  "expires_at": "2025-01-07T12:00:00Z"
}

Response Fields

Field	Type	Description
user_identifier	string	The user identifier that was provided
login_url	string	URL to embed in iframe (valid for 24 hours)
expires_at	string	ISO 8601 timestamp when the session expires

Examples

Basic User Session

const response = await fetch('https://api.pocketdns.com/api/v1/users', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    user_identifier: 'user_123'
  })
});

const { login_url } = await response.json();

User Session with Email

const response = await fetch('https://api.pocketdns.com/api/v1/users', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    user_identifier: 'user_123',
    email: 'user@example.com'
  })
});

const session = await response.json();

Error Responses

400 Bad Request

{
  "error": "validation_error",
  "message": "user_identifier is required",
  "details": {
    "field": "user_identifier",
    "code": "missing_required_field"
  }
}

401 Unauthorized

{
  "error": "unauthorized",
  "message": "Invalid API key"
}

422 Unprocessable Entity

{
  "error": "validation_error",
  "message": "Invalid email format",
  "details": {
    "field": "email",
    "code": "invalid_format"
  }
}

Get User Details

Retrieves information about a specific user.

Endpoint: GET /api/v1/users/{user_identifier}

Request

GET /api/v1/users/user_123
Authorization: Bearer YOUR_API_KEY

Response

{
  "user_identifier": "user_123",
  "email": "user@example.com",
  "created_at": "2025-01-01T00:00:00Z",
  "last_login": "2025-01-06T12:00:00Z",
  "domain_count": 5,
  "total_spent": "125.50"
}

Examples

const response = await fetch('https://api.pocketdns.com/api/v1/users/user_123', {
  headers: {
    'Authorization': 'Bearer sk_live_...'
  }
});

const user = await response.json();
console.log(`User has ${user.domain_count} domains`);

List Users

Retrieves a paginated list of users.

Endpoint: GET /api/v1/users

Request

GET /api/v1/users?limit=50&offset=0&sort=created_at
Authorization: Bearer YOUR_API_KEY

Query Parameters

Parameter	Type	Default	Description
limit	integer	50	Number of users to return (max 100)
offset	integer	0	Number of users to skip
sort	string	created_at	Sort field (created_at, last_login, domain_count)
order	string	desc	Sort order (asc or desc)

Response

{
  "users": [
    {
      "user_identifier": "user_123",
      "email": "user@example.com",
      "created_at": "2025-01-01T00:00:00Z",
      "last_login": "2025-01-06T12:00:00Z",
      "domain_count": 5
    }
  ],
  "total": 1247,
  "limit": 50,
  "offset": 0
}

Examples

// Get first 25 users
const response = await fetch('https://api.pocketdns.com/api/v1/users?limit=25', {
  headers: {
    'Authorization': 'Bearer sk_live_...'
  }
});

const { users, total } = await response.json();
console.log(`Showing ${users.length} of ${total} users`);

Update User

Updates user information.

Endpoint: PUT /api/v1/users/{user_identifier}

Request

PUT /api/v1/users/user_123
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "email": "newemail@example.com"
}

Parameters

Parameter	Type	Required	Description
email	string	No	New email address

Response

{
  "user_identifier": "user_123",
  "email": "newemail@example.com",
  "updated_at": "2025-01-06T12:30:00Z"
}

Examples

const response = await fetch('https://api.pocketdns.com/api/v1/users/user_123', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer sk_live_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'updated@example.com'
  })
});

const updatedUser = await response.json();

Delete User

Deletes a user and all associated data.

Endpoint: DELETE /api/v1/users/{user_identifier}

Request

DELETE /api/v1/users/user_123
Authorization: Bearer YOUR_API_KEY

Response

204 No Content

Examples

const response = await fetch('https://api.pocketdns.com/api/v1/users/user_123', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer sk_live_...'
  }
});

if (response.status === 204) {
  console.log('User deleted successfully');
}

Common Error Codes

Status Code	Error Code	Description
400	validation_error	Request data is invalid
401	unauthorized	Invalid or missing API key
404	not_found	User not found
409	conflict	User identifier already exists
422	unprocessable_entity	Data format is correct but values are invalid
429	rate_limit_exceeded	Too many requests
500	internal_error	Server error

Rate Limits

• User creation: 100 requests per minute
• User retrieval: 1000 requests per minute
• User updates: 60 requests per minute
• User deletion: 30 requests per minute

Rate limit headers are included in all responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1641472800

Best Practices

1. Cache user sessions to avoid unnecessary API calls
2. Handle rate limits gracefully with exponential backoff
3. Validate user identifiers before sending to API
4. Use meaningful user identifiers for easier debugging
5. Include email when available for better user experience
6. Check session expiration before using login URLs