---
title: Specify realms in REST API calls
description: Specify realms in PingAM REST API calls using DNS aliases or path parameters
component: pingam
version: 7.5
page_id: pingam:am-rest:rest-realms
canonical_url: https://docs.pingidentity.com/pingam/8.1/am-rest/rest-realms.html
llms_txt: https://docs.pingidentity.com/pingam/llms.txt
docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md
keywords: ["REST API", "Realms"]
page_aliases: ["REST-guide:rest-realms.adoc"]
superseded_by: https://docs.pingidentity.com/pingam/8.1/am-rest/rest-realms.html
---

# Specify realms in REST API calls

Realms can be specified in the following ways when making a REST API call to AM:

* DNS alias

  When making a REST API call, the DNS alias of a realm can be specified in the subdomain and domain name components of the REST endpoint.

  To list all users in the Top Level Realm use the DNS alias of the AM instance, for example:

  ```
  https://openam.example.com:8443/openam/json/users?_queryId=*
  ```

  To list all users in a realm with DNS alias `suppliers.example.com` the REST endpoint would be:

  ```
  https://suppliers.example.com:8443/openam/json/users?_queryId=*
  ```

* Path

  When making a REST API call, specify the realm in the path component of the endpoint. You must specify the entire hierarchy of the realm, starting at the Top Level Realm. Prefix each realm in the hierarchy with the `realms/` keyword. For example, `/realms/root/realms/customers/realms/europe`.

  To authenticate a user in the Top Level Realm, use the `root` keyword. For example:

  ```
  https://openam.example.com:8443/openam/json/realms/root/authenticate
  ```

  To authenticate a user in a subrealm named `alpha`, the REST endpoint would be:

  ```
  https://openam.example.com:8443/openam/json/realms/root/realms/alpha/authenticate
  ```

  If realms are specified using both the DNS alias and path methods, the path is used to determine the realm.

  For example, the following REST endpoint returns users in a realm named `bravo`, not the realm with DNS alias `suppliers.example.com`:

  ```
  https://suppliers.example.com:8443/openam/json/realms/root/realms/bravo/users?_queryId=*
  ```