---
title: Specify realms in REST API calls
description: Realms can be specified in the following ways when making a REST API call to AM:
component: pingam
version: 8.1
page_id: pingam:am-rest:rest-realms
canonical_url: https://docs.pingidentity.com/pingam/8.1/am-rest/rest-realms.html
keywords: ["REST API", "Realms"]
page_aliases: ["REST-guide:rest-realms.adoc"]
---

# 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:

  ```none
  https://am.example.com:8443/am/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/am/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:

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

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

  ```none
  https://am.example.com:8443/am/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/am/json/realms/root/realms/bravo/users?_queryId=*
  ```