canonical: https://jentic.com/apis/azure.com/relay

# Microsoft Azure Relay

Jentic publishes the only available OpenAPI specification for Relay, keeping it validated and agent-ready. The API manages Azure Relay resources under Microsoft.Relay through Azure Resource Manager - namespaces that host the relay endpoints, hybrid connections that bridge on-premises services to cloud clients, and WCF relays that expose legacy WCF services. It also covers the authorization-rule and access-key surface used by clients on each side of the relay.

## For AI agents

Provision Azure Relay namespaces, create hybrid connections and WCF relays, and manage the authorization rules and access keys that clients use to connect.

## Scope

Does not send messages over the relay, run the on-premises listener, or expose Service Bus queues - use for the Microsoft.Relay control-plane lifecycle of namespaces, hybrid connections, WCF relays, and authorization rules only.

## Capabilities

- Provision an Azure Relay namespace in a resource group
- Create a hybrid connection that bridges on-premises services to cloud clients
- Create a WCF relay endpoint to expose a WCF service via Azure
- Define authorization rules at namespace, hybrid connection, or WCF relay scope
- List and rotate the access keys associated with an authorization rule
- Check whether a namespace name is available before provisioning
- List relays and hybrid connections inside a namespace

## Use cases

### Bridge on-premises services to the cloud

Hybrid Connections in Azure Relay let an on-premises service expose itself to cloud clients without opening inbound firewall ports. The API provisions the namespace, creates the named hybrid connection, and issues the authorization rules and keys the listener and sender each need, so the connection can be set up entirely from automation.

Example prompt: Create namespace 'relay-hybrid-prod' and hybrid connection 'orders-onprem' with a Listen rule for the on-prem listener and a Send rule for the cloud client

### Expose legacy WCF services

Workloads that still run WCF services use Azure Relay's WCF relays to expose those endpoints to remote clients without standing up a full VPN. The API supports per-namespace listings, lifecycle CRUD, and per-relay authorization rules so a fleet of WCF relays can be managed alongside the rest of the resource group.

Example prompt: Create a WCF relay 'orders-wcf' inside namespace 'relay-hybrid-prod' and add a Send authorization rule for the cloud client

### Access key rotation

Every authorization rule on a relay namespace, hybrid connection, or WCF relay has primary and secondary keys that clients use to connect. The API exposes listKeys and regenerateKeys on each rule so rotations can be staged across the listener and sender without dropping the connection.

Example prompt: Regenerate the secondary key on the 'cloud-sender' authorization rule of hybrid connection 'orders-onprem'

### Multi-tenant relay topology

Platform teams provisioning relay capacity for many tenants list namespaces and hybrid connections at subscription and resource-group scope to inventory the topology, then create per-tenant authorization rules with scoped Listen or Send rights so each tenant gets isolated credentials.

Example prompt: List all hybrid connections in namespace 'relay-shared' and create a tenant-specific Listen rule on each one

### Agent-driven hybrid connectivity

An AI agent fronting a partner-onboarding portal accepts a partner identifier, provisions a per-partner hybrid connection in a shared relay namespace, mints the listener and sender authorization rules with scoped rights, and returns the connection details. Jentic isolates the AAD client secret so the agent only sees scoped bearer tokens.

Example prompt: Onboard partner X by creating a hybrid connection, Listen and Send rules, and returning the connection string for each side

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| PUT | /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Relay/namespaces/{namespaceName} | Create or update a Relay namespace |
| GET | /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Relay/namespaces/{namespaceName} | Get a specific Relay namespace |
| PUT | /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Relay/namespaces/{namespaceName}/hybridConnections/{hybridConnectionName} | Create or update a hybrid connection |
| PUT | /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Relay/namespaces/{namespaceName}/wcfRelays/{relayName} | Create or update a WCF relay |
| PUT | /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Relay/namespaces/{namespaceName}/authorizationRules/{authorizationRuleName} | Create or update a namespace authorization rule |
| POST | /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Relay/namespaces/{namespaceName}/authorizationRules/{authorizationRuleName}/listKeys | List access keys for a namespace authorization rule |
| POST | /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Relay/namespaces/{namespaceName}/authorizationRules/{authorizationRuleName}/regenerateKeys | Regenerate access keys for an authorization rule |
| POST | /subscriptions/{subscriptionId}/providers/Microsoft.Relay/checkNameAvailability | Check if a namespace name is available |

## Key resources

- **Namespaces** — Provisioning, listing, update, and delete of Azure Relay namespaces
- **Hybrid Connections** — Bridge on-premises services to cloud clients via named hybrid connections
- **WCF Relays** — Expose WCF service endpoints via Azure Relay
- **Authorization Rules** — Per-resource Listen, Send, and Manage rules with primary and secondary keys

## Why Jentic

- **Setup:** Wiring Azure Relay by hand means registering an Azure AD app for OAuth 2.0, acquiring bearer tokens against management.azure.com, and polling the long-running namespace create operations yourself. Through Jentic you install once, import Relay from the API Directory, store the Azure AD credential once, and your agent calls it.
- **Permission scoping:** The subscription, resource group, namespace, and the hybrid connection, WCF relay, or authorization rule name all travel in the URL path (/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Relay/namespaces/{namespaceName}/...), so a rule can pin your agent to one namespace and the operations it needs, such as creating hybrid connections and listing keys. You choose the operations it may call, so destructive ones like deleting a WCF relay or regenerating authorization keys are not included unless you add them.
- **Credential handling:** Your Azure AD OAuth 2.0 credential is stored once, encrypted, by your own Jentic One instance and a scoped bearer token is injected at execution time. The client secret and any returned relay keys never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create an azure hybrid connection' or 'rotate a relay authorization key', and Jentic returns the matching operation with its input schema so the agent supplies the namespace, hybrid connection name, and rights without browsing the reference docs.

## Related APIs

- **Service Bus Management Client** — Manages Service Bus messaging entities that often pair with Relay for reliable async patterns
- **Event Hub 2018 Preview Management Client** — Manages high-throughput event ingestion that complements Relay for streaming workloads
- **Notification Hubs Management Client** — Push messaging service for fan-out to mobile clients rather than service-to-service bridging

## FAQ

### Why is there no official OpenAPI spec for Relay?

Microsoft Azure does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Relay via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Azure Relay Management API use?

The API runs through Azure Resource Manager and uses OAuth 2.0 bearer tokens issued by Azure Active Directory under the azure_auth scheme with the user_impersonation scope. Through Jentic, the AAD client secret is held in the encrypted vault and a short-lived access token is supplied at execute time so the secret never appears in the agent's context.

### Can I scope authorization rules to Listen or Send only?

Yes. PUT .../authorizationRules/{authorizationRuleName} accepts a rights array containing Listen, Send, and Manage. Listeners on the on-premises side typically need Listen, while cloud clients are issued a separate Send-only rule, with each rule's keys returned via the listKeys POST endpoint.

### What are the rate limits for the Azure Relay Management API?

Azure Resource Manager applies subscription-level read and write throttles (around 12,000 reads per hour and 1,200 writes per hour per region per subscription) and returns 429 with a Retry-After header when exceeded. Namespace create operations are long-running and should be polled with backoff.

### How do I create a hybrid connection through Jentic?

Search Jentic for 'create azure hybrid connection', load the schema for PUT .../namespaces/{namespaceName}/hybridConnections/{hybridConnectionName}, then execute with subscriptionId, resourceGroupName, namespaceName, hybridConnectionName, and the requiresClientAuthorization flag. The pip install jentic Python SDK uses the async search, load, execute pattern.

### Is the Azure Relay Management API free?

There is no per-call charge for the management API itself; you pay for the Azure Relay namespace based on the number of listeners and the messages or hours consumed by hybrid connections and WCF relays. Listing and key-management calls are not separately metered.

### Can I limit what my agent is allowed to do with the Azure Relay API?

Yes. Because your Jentic One instance is self-hosted, your own rules decide which operations and credentials the agent may use. Since the subscription, resource group, namespace, and resource name all travel in the URL path, a rule can pin the agent to a single namespace and only the operations it needs, such as creating hybrid connections, defining Listen or Send authorization rules, and listing keys. You choose the operations it may call, so destructive ones like deleting a WCF relay or regenerating authorization keys are excluded unless you explicitly add them.