IPinfo Integration Guide: Bring Your Own License (BYOL)
IPinfo provides access to its data services in four ways:
When it comes to the API service and data downloads, access is controlled by an IPinfo Access Token (a 14-character alphanumeric token).
- Free accounts get access to IPinfo Lite API + IPinfo Lite database.
- Paid accounts get access to the specific APIs or databases they’re subscribed to.
The idea behind Bring Your Own License (BYOL) is simple:
- If a platform wants to support IPinfo services, its users can sign up for IPinfo and provide their own access token.
- The integration platform acts as an intermediate layer, making API requests or database downloads on behalf of the user using their token.
- The platform itself never manages global IPinfo tokens each user brings their own.
Recommended reading: Data Downloads vs API, or Both?
BYOL Integration: IPinfo API Service
API Endpoints
- Current:
https://api.ipinfo.io - Legacy:
https://ipinfo.io(still supported indefinitely; but not recommended)
Both support HTTPS and can be hardcoded in your integration.
Lite and paid plans aren't just different data, they're different endpoints and limits too:
| IPinfo Lite | Paid plans (Core / Plus / Max) | |
|---|---|---|
| Endpoint | https://api.ipinfo.io/lite/{ip} | https://api.ipinfo.io/lookup/{ip} |
| Requests | Unlimited, no daily/monthly cap | Monthly request quota set by your plan; 429 once exceeded (or continues via overages if metered billing is enabled) |
| Data returned | Country-level geolocation + basic ASN only | Full response for your subscribed plan, see the Core, Plus, and Max docs |
Key resources:
Best Practices for API Integration
We recommend starting with IPinfo Lite API to validate your integration.
- Sign up for your free account using a company or project email address (preferably an integration or partnership email domain), rather than a personal one, so we can identify the integration source.
- You can even integrate the Lite API directly into the platform, as the IPinfo Lite API has a commercial/redistribution-friendly license.
- You can create a project specific access token to support IPinfo Lite API access across all users.
Once your IPinfo Lite integration works end to end, you can move on to supporting our paid plans (API and database downloads). We don't offer trial access to paid API or database download services, so build against the documentation, schema, and sample data below before you're holding a paid token:
- API schema and samples: the Core, Plus, and Max docs each include full sample responses for their plan. For a machine-readable version of every response shape, see the OpenAPI spec.
- Database download schema and samples: start with the Database Downloads docs, then the Database Filename Reference for the storage URIs and their matching sample dataset URIs. Sample datasets are downloadable by anyone without an IPinfo Access Token, regardless of plan; for IPinfo Lite, Core, and Plus specifically, the sample-database repo also includes full sample API responses.
- Building with AI tooling: if you're using an AI coding assistant to help replicate your Lite integration across the paid plans, our full documentation is also available as a single markdown file built for LLMs, see LLM Resources.
Once you've explored the schema and samples for the plan you're integrating:
- Use official IPinfo SDKs/libraries for built-in caching, async requests, and bulk lookups. For database downloads, we recommend using an MMDB reader library.
- Implement asynchronous requests and use bulk endpoints for enrichment.
- Send a uniquely identifiable
User-Agentheader on every request, for API calls and database downloads alike, so we can attribute usage back to your platform and troubleshoot issues faster. - Cache responses to avoid duplicate lookups and reduce quota usage.
- Handle errors and rate limits gracefully:
429→ rate limited (retry with backoff)403→ invalid token
- Timeouts/retries as per your SLA
- Keep integration dynamic since responses depend on the customer’s subscription tier.
Examples:
BYOL Integration: IPinfo Data Downloads
Supported Formats for data downloads:
- MMDB (recommended for lookups)
- Parquet (recommended for analytics)
- CSV and JSON (compressed, uncompress before ingestion)
References:
Best Practices for Data Downloads
- Start with IPinfo Lite IP database.
- You can integrate the Lite Data Downloads directly into the platform, as the IPinfo Lite Data Downloads has a commercial/redistribution-friendly license.
- You can create a project specific access token to support IPinfo Lite Data Downloads access across all users.
- Use stable download URLs from the filename reference.
- Develop against sample datasets before using production data.
- Validate dataset integrity with the checksums endpoint:
- Automate download, verification, and refresh.
- Prioritize MMDB file format for optimal IP lookup performance.
- Be mindful of update cadence (daily, weekly, biweekly, monthly).
Example:
BYOL Integration: Production Readiness
Moving from prototype to production? Follow these steps:
- Staging Rollout: Deploy to a non-production environment and replay representative traffic.
- Validation Checklist
- Schema alignment
- Authentication flow works with BYOL tokens
- Rate limits respected; backoff logic in place
- Caching strategy documented
- Errors handled (timeouts, retries, rate limits)
- Monitoring
- Request counts, latency, and error codes
- Cache hit/miss ratio
- Alerts for quota breaches and failures
- Security Review
- Access controls for stored datasets
- Data retention policies
Go-Live Checklist
- Correct datasets + refresh cadence configured
- Authentication tested with BYOL credentials
- Throughput within limits; graceful retry/backoff implemented
- Dashboards/alerts created for usage and errors
- Runbook in place for incidents (contacts, rollback steps)
- Contract/licensing terms reflected in deployment notes: IPinfo Lite requires attribution under its license terms; for paid plans, confirm terms with your IPinfo partner manager
- Set up a uniquely identifiable
User-Agentheader (e.g.YourPlatformName/1.2.0) on every request, so usage can be attributed back to your platform and support can troubleshoot more efficiently - Development and testing were validated against sample data before go-live: the sample-database repo includes sample datasets and sample API responses for paid plans too, not just Lite, specifically IPinfo Core and IPinfo Plus (IPinfo Max is an API-only plan with no corresponding database product, so it isn't part of this repo; see the response examples in the Max API docs instead)
Where to get help
- Support: For technical assistance, please contact support@ipinfo.io and include your environment, integration method, and a brief description of the error/goal to speed up troubleshooting.
- Partner contact: Your IPinfo partner manager for commercial or scope questions.
- Feedback on these docs: We welcome feedback to improve our docs. Please send suggestions to alliances@ipinfo.io
Staying up to date
- Release notes & dataset changes: Subscribe to IPinfo product newsletter to track schema updates, new fields, and deprecations.
- Roadmap & feature requests: Share requests and priorities via your partner manager.