Repository Public
1# Private Link23> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.45OpenAI Private Link lets Azure workloads reach regional OpenAI API endpoints through Azure Private Link instead of connecting directly to public API endpoints. Create a private endpoint for each OpenAI-provided regional Private Link Service, map its regional host name in private DNS, and send normal authenticated API requests to that host name.67Use Private Link when your organization has strict requirements to keep traffic on Azure private networking. If you don't have private-network requirements, OpenAI's public endpoints are simpler to set up and operate. Private Link isn't compatible with IP allowlist controls or mutual TLS (mTLS); contact OpenAI if you need help choosing the right enterprise network controls.89Private Link is currently not self-service. Work with your OpenAI contact or10 [contact sales](https://openai.com/contact-sales/) to request access and11 receive the regional Private Link Service aliases or resource identifiers you12 need.1314## Understand how Private Link works1516Some customers have been using the legacy Private Link solution (v1), which connects each Private Endpoint to a specific OpenAI API cluster. The current regional solution differs in these ways:1718| | Legacy Private Link (v1) | Regional Private Link |19| --------------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |20| Host name | Cluster-specific, such as `privatelink.enterprise.unified-1.api.openai.com` | Regional, such as `southcentralus.privatelink.api.openai.com` |21| OpenAI routing | Pinned to one OpenAI API cluster | Regional private-edge gateway that can route to more than one backing OpenAI API cluster |22| Customer health check | Older v1 health check paths | `GET /v2/privatelink_healthcheck` |2324A request follows this path:25261. Your application resolves a regional Private Link host name through your private DNS.272. The host name resolves to an Azure Private Endpoint in your virtual network.283. The Private Endpoint connects to the regional OpenAI Private Link Service.294. The Private Link Service sends the request to OpenAI's regional private-edge gateway.305. The gateway routes the request to an enterprise-enabled backing OpenAI API cluster for that regional rail.3132Within a regional rail, Private Link can route around an unavailable backing cluster and OpenAI can add backing clusters without requiring you to reconfigure your Private Endpoints. It doesn't automatically move traffic from the regional host name you selected to a different regional Private Endpoint. Don't assume that Private Link inherits OpenAI's public endpoint routing behavior; configure how your application fails over between regions.3334## Choose regional endpoints3536OpenAI provides the exact Private Link Service alias or resource identifier during onboarding. The current production regional host names are:3738| Region label | Customer host name |39| ------------------ | ------------------------------------------- |40| South Central US | `southcentralus.privatelink.api.openai.com` |41| West US | `westus.privatelink.api.openai.com` |42| East US 2 | `eastus2.privatelink.api.openai.com` |43| Spain Central / EU | `spaincentral.privatelink.api.openai.com` |4445The Spain Central / EU host name can route to backing clusters in other EU regions, such as North Europe.4647## Set up Private Link4849### 1. Provide onboarding information5051Send OpenAI:5253- The Azure subscription IDs that need access to the OpenAI Private Link Services.54- Your OpenAI organization ID.55- The regions you need.56- Operational contacts for maintenance and regional traffic-switching notices.5758OpenAI grants the subscriptions visibility and approval for the appropriate regional Private Link Services, then provides the Private Link Service aliases or resource identifiers.5960### 2. Create private endpoints6162Create one Private Endpoint for each selected region. Azure requires a Private Endpoint to share the region of the customer virtual network. Set `--location` to that region, which might differ from the OpenAI Private Link Service region.6364The following command uses an OpenAI-provided Private Link Service resource identifier:6566```bash67az network private-endpoint create \68 --name openai-privatelink-southcentralus \69 --resource-group <customer-resource-group> \70 --location <customer-vnet-region> \71 --vnet-name <customer-vnet> \72 --subnet <customer-private-endpoint-subnet> \73 --private-connection-resource-id <openai-provided-pls-resource-id> \74 --connection-name openai-privatelink-southcentralus75```7677If OpenAI provides an alias, use the alias and add `--manual-request true`:7879```bash80az network private-endpoint create \81 --name openai-privatelink-southcentralus \82 --resource-group <customer-resource-group> \83 --location <customer-vnet-region> \84 --vnet-name <customer-vnet> \85 --subnet <customer-private-endpoint-subnet> \86 --private-connection-resource-id <openai-provided-pls-alias> \87 --connection-name openai-privatelink-southcentralus \88 --manual-request true89```9091Azure requires `--manual-request true` for [alias connections](https://learn.microsoft.com/en-us/azure/private-link/private-endpoint-overview#connect-by-using-an-alias); subscriptions on the access list can still receive automatic approval.9293Use a similar Azure portal or Terraform workflow if your organization manages Private Endpoints through infrastructure as code.9495### 3. Test connectivity before changing DNS9697After OpenAI approves the Private Endpoint and Azure provisions it, capture its private IP address. Use `curl --resolve` to test the regional host name without changing DNS globally:9899```bash100curl -v \101 --resolve southcentralus.privatelink.api.openai.com:443:<PRIVATE_ENDPOINT_IP> \102 https://southcentralus.privatelink.api.openai.com/v2/privatelink_healthcheck103```104105A healthy response returns HTTP `200` with a message like:106107```json108{ "message": "Service is up" }109```110111Use the exact health check path: `/v2/privatelink_healthcheck`. Keep automated health check traffic low: use at most 1 QPS per regional endpoint unless OpenAI approves a different rate.112113### 4. Configure private DNS114115Create private DNS records so each regional OpenAI Private Link host name resolves to its corresponding Private Endpoint IP address inside your network:116117| Host name | Private Endpoint IP address |118| ------------------------------------------- | -------------------------------------- |119| `southcentralus.privatelink.api.openai.com` | `<southcentralus-private-endpoint-ip>` |120| `westus.privatelink.api.openai.com` | `<westus-private-endpoint-ip>` |121| `eastus2.privatelink.api.openai.com` | `<eastus2-private-endpoint-ip>` |122| `spaincentral.privatelink.api.openai.com` | `<spaincentral-private-endpoint-ip>` |123124Check DNS and connectivity from the same network path your application uses:125126```bash127nslookup southcentralus.privatelink.api.openai.com128curl -v https://southcentralus.privatelink.api.openai.com/v2/privatelink_healthcheck129```130131### 5. Fail over between regions132133Private Link provides a regional front door, but your traffic still targets the regional host name you select. Configure your client, service mesh, DNS layer, or load-balancing layer to fail over between regions.134135Recommended behavior:136137- Probe each configured region with `GET /v2/privatelink_healthcheck`.138- Treat HTTP `200` as available.139- Treat `5xx` responses, connection errors, TLS errors, or repeated timeouts as unavailable.140- Fail over only after a small number of consecutive errors to avoid flapping.141- Continue probing an unavailable region in the background and fail back according to your operational policy.142143The regional health check reflects the health of the OpenAI API clusters behind the private-edge rail. A region with no known backing clusters, missing health configuration, or insufficient healthy backing clusters returns an error.144145If your routing decision depends on a specific API or model, pair this health check with a low-rate synthetic request to that API and model from the same network path.146147### 6. Update application base URLs148149Use the regional Private Link host name as the OpenAI API base URL:150151```python152from openai import OpenAI153154client = OpenAI(155 base_url="https://southcentralus.privatelink.api.openai.com/v1",156)157```158159```ruby160client = OpenAI::Client.new(161 base_url: "https://southcentralus.privatelink.api.openai.com/v1"162)163```164165166The SDK reads `OPENAI_API_KEY` from your environment.167168You can also call the regional endpoint directly:169170```bash171curl https://southcentralus.privatelink.api.openai.com/v1/responses \172 -H "Authorization: Bearer $OPENAI_API_KEY" \173 -H "Content-Type: application/json" \174 -d '{175 "model": "gpt-6-astra",176 "input": "Say hello from Private Link."177 }'178```179180181Start in a development or staging environment, then promote traffic gradually.182183## Check your configuration184185Use this checklist while onboarding or migrating to Private Link:186187- OpenAI has confirmed that your Azure subscription IDs can access the selected regional Private Link Services.188- You created Private Endpoints, and OpenAI approved them for each selected region.189- You recorded the Private Endpoint IP addresses.190- `curl --resolve` succeeds against `/v2/privatelink_healthcheck`.191- Private DNS resolves regional host names to Private Endpoint IP addresses from the application network.192- The application can call a representative `/v1` API endpoint through the regional host name.193- Health check automation is rate-limited and logs the region, status code, and error type for errors.194- You tested how the application fails over by forcing a region unhealthy in a controlled environment.195- Your operational documentation identifies who can change DNS, Private Endpoint configuration, and application regional routing.196197## Check endpoint compatibility198199The following matrix reflects the current deployment configuration for services behind the listed public API routes. It doesn't replace live customer validation: test model availability, product gates, downstream dependencies, request-size limits, streaming behavior, and WebSocket behavior in each target region. `Yes` means every backing cluster in the regional rail has the route; `No` means the backing service is absent from that rail.200201| Endpoint family | South Central US | West US | East US 2 | Spain Central / EU |202| --------------------------------------- | ---------------- | ------- | --------- | ------------------ |203| `/v1/responses` | Yes | Yes | Yes | Yes |204| `/v1/chat/completions` | Yes | Yes | Yes | Yes |205| `/v1/completions` | Yes | Yes | Yes | Yes |206| `/v1/embeddings` | Yes | Yes | Yes | Yes |207| `/v1/audio/*` (Inference) | Yes | Yes | Yes | Yes |208| `/v1/audio/*` (management) | Yes | No | No | Yes |209| `/v1/models` | Yes | Yes | Yes | Yes |210| `/v1/files`, `/v1/uploads` | Yes | Yes | Yes | Yes |211| `/v1/batches` | Yes | Yes | Yes | Yes |212| `/v1/images/*` | Yes | Yes | Yes | Yes |213| `/v1/moderations` | Yes | Yes | Yes | Yes |214| `/v1/vector_stores` | Yes | Yes | Yes | Yes |215| `/v1/organization/audit_logs` | Yes | Yes | Yes | Yes |216| Other `/v1/organization/*`, `/v1/usage` | Yes | No | No | Yes |217| `/v1/realtime` | Yes | Yes | Yes | Yes |218219## Frequently asked questions220221### Does Private Link fail over between regions automatically?222223No. The regional private-edge rail can route across its configured backing clusters, but it doesn't automatically move your traffic to a different regional Private Endpoint. Configure your application to fail over across the regional endpoints you use.224225### Which health check should I use?226227Use `GET /v2/privatelink_healthcheck` on the regional host name. The older v1 health check paths probe the backing-cluster health rail, so don't use them as customer-facing probes.228229### Which API host name should applications use?230231Use the regional host name with the normal `/v1` API path, such as `https://southcentralus.privatelink.api.openai.com/v1`.232233### Can AWS or Google Cloud workloads connect through Private Link?234235Not directly. Private Link connectivity is Azure-specific. Workloads in AWS or Google Cloud can connect only through customer-managed networking into Azure, such as an Azure proxy or cross-cloud private connectivity pattern, and then from Azure to OpenAI over Azure Private Link.236237### Does Private Link change authentication?238239No. Private Link changes only the network path. Requests still need normal OpenAI API authentication and authorization.240241### Does Private Link support every OpenAI API?242243No. Support depends on whether an API is available on every backing cluster for the selected regional rail. Use the compatibility matrix as a starting point, then test each API surface and model you need in every target region.