How-To: Call the EZRADIUS API with Swagger Documentation

Overview - What is the EZRADIUS API?

The EZRADIUS API allows you to interact with your EZRADIUS subscriptions, policies, and other resources programmatically. With the API, you can automate tasks, integrate with other systems, and take actions directly from your applications.

What Can You Do with the EZRADIUS API?

Anything you can do in the EZRADIUS portal, you can also do through the API. This includes:

• Managing EZRADIUS subscriptions
• Creating and updating access policies
• Retrieving audit logs
• …plus any other action available in the portal

To see the full list of available API endpoints and their capabilities, check out the EZRADIUS API Swagger Documentation.

Who Can Use the EZRADIUS API?

The EZRADIUS API is available to all EZRADIUS customers. Since it’s what powers the EZRADIUS portal, any user or application with access to the portal can also call the API, as long as they have the necessary permissions. To restrict access to the API, make sure your EZRADIUS roles and permissions are set up correctly.

What Services Can the EZRADIUS API Integrate With?

The EZRADIUS API can be called from any service or application that can make HTTP requests and handle bearer token authentication. In Azure, you can easily call the API using a managed identity or service principal from services like Azure Functions, Azure Logic Apps, Azure Automation, and more. You can also call the API from your own custom applications, scripts, or any other environment that supports HTTP requests.

What Identities Can Call the API?

The EZRADIUS API can be called using any Entra ID user account or Entra ID applications, including service principals and managed identities.

There are two common ways to interact with the API:

• Delegated Access: Have a user take actions and use their own credentials to call the API. They will have the same permissions as they have in the EZRADIUS portal. Best for frontend applications where users are directly interacting with the API.
• Application Access: Create an Entra ID application and use its credentials to call the API. This allows you to grant specific permissions to the application, independent of any user. Best for backend applications or services that need to run without user interaction.

Step-by-Step Guide: How to Call the EZRADIUS API Programmatically

The following steps will guide you through the process of calling the EZRADIUS API programmatically.

Prerequisite for Calling the EZRADIUS API

Before you can call the EZRADIUS API, make sure you have admin consented the EZRADIUS application in your Entra ID tenant. Without this step, you won’t be able to authenticate and call the API.

Step 1: Create the Identity That Will Call the API

To call the EZRADIUS API, you need to create an identity that will be used for authentication. This can be either an Entra ID user account or an Entra ID application (service principal or managed identity).

• Entra ID User Account
• Entra ID Application

Step 2: Grant Permissions to the Identity

To call the EZRADIUS API, the identity you created in Step 1 needs to have the appropriate permissions on your EZRADIUS subscription. The API uses the same role-based access control (RBAC) model as the EZRADIUS portal, so you can assign roles to your users, groups, and applications to control what they can do with the API.

Refer to our subscription management documentation for more details on how to assign roles and permissions.

You should see the Friendly Name and Object/Client ID of the identity you just assigned a role to in the list of users and applications with access to the subscription:

Step 3: Get a Token to Authenticate with the EZRADIUS API

To authenticate with the EZRADIUS API, you need to obtain a bearer token from Entra ID. The process for getting a token depends on the type of identity you’re using (user account or application) and the authentication flow you choose.

• Entra ID User Account
• Entra ID Application

az login
az account get-access-token

az login --identity
az account get-access-token

az login --service-principal -u <CLIENT_ID> -p <CLIENT_SECRET> --tenant <TENANT_ID>
az account get-access-token

Step 4: Pick Your API Endpoint

When calling the EZRADIUS API, make sure to use the correct base URL for your region. The base URL for the API depends on your region.

EZRADIUS API Endpoints

EZRADIUS runs in seven different instances, each hosted in different regions to provide low latency and data residency for customers around the world. The endpoints for each instance are as follows:

If you have a dedicated instance of EZRADIUS, your endpoint will be in the format https://<your-instance-name>.ezradius.io. Please visit portal.ezradius.io to find the endpoint for your instance.

Step 5: Make Your EZRADIUS API Call

Now that you have your token and know which endpoint you want to call, you can make your API request. The API uses standard HTTP methods (GET, POST, PUT, DELETE) and expects the bearer token in the Authorization header. Here’s an example of how to call the API using curl:

curl -X GET "https://<REGION>.ezradius.io/api/Policies/GetUserInfo" \
    -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
    -H "Content-Type: application/json"

You should receive a response from the API with information about the account used to authenticate:

{
    "TenantId":"<TENANT_ID>",
    "UserGuid":"<USER_GUID>",
    "UserName":"<USER_NAME>",
    "FirstName":"<FIRST_NAME>",
    "Email":"<EMAIL>",
    "Type":"<USER_TYPE>"
}

You can also enter your bearer token directly in the Swagger documentation to test out different API endpoints and see the responses in real-time. Just click the “Authorize” button in the Swagger UI, enter your token, and then you can make API calls directly from the documentation. To view the Swagger documentation, navigate to https://<REGION>.ezradius.io/swagger/index.html, replacing <REGION> with the region your subscription is in.

Troubleshooting Tips for Calling the EZRADIUS API

If you run into issues when calling the EZRADIUS API, here are some troubleshooting tips to help you resolve common problems:

I Got a 200 OK Response, But There is No Data

If you receive a 200 OK response but the data is empty or not what you expected, you might be calling the wrong endpoint or you may not have permission to your EZRADIUS subscription.

First, make sure you’re calling the correct instance of EZRADIUS for your region, and double-check the API endpoint you’re using. Refer to the EZRADIUS API Endpoints section above to confirm you’re using the correct base URL and endpoint for your region.

Next, check that the identity you’re using to call the API has the correct role assigned in your EZRADIUS subscription. If the identity doesn’t have permission to access the subscription, you may get an empty response or a response that doesn’t include the data you expected. See the Grant Permissions section above for more information on how to assign roles and permissions.

I Got a User Does Not Have Permission Error

If you receive an error indicating that the user or application does not have permission to call the API, it’s likely that the identity you’re using does not have the necessary role assigned in your EZRADIUS subscription. Refer to the Grant Permissions section above to ensure that the identity has the appropriate role assigned.

I Cannot Add My Entra ID Application to an Owner Role

If you’re trying to assign the Owner Role to an Entra ID application (service principal or managed identity) and are unable to do so, this is because EZRADIUS currently restricts the Owner Role to users only. This means that service principals and managed identities cannot be assigned the Owner Role. If you need Owner-level permissions for an application, please reach out to our team to discuss your scenario and potential solutions. In the meantime, you can use the Network Administrator or Log Readers role for application-based access to the API.

I’m Still Having Issues

If you’ve tried the troubleshooting tips above and are still having issues calling the EZRADIUS API, please don’t hesitate to reach out to our support team for assistance.