Using the Authentication and Token Management REST APIs

Explains the usage of the Authentication and Token Management APIs with some generic samples.

The Authentication and Token Management API uses the v1 version.

If you want to perform common operations using the Authentication and Token REST API, then refer the section Using the Common REST API Endpoints.

The following table provides section references that explain usage of some of the Authentication and Token REST APIs. It includes sample examples to work with the Authentication and Token functions. If you want to view all the Authentication and Token APIs, then use the /doc API to retrieve the API specification.

Category	REST API
Token Management	Generate token
	Refresh token
	Invalidate a user session
	Update access token lifespan and SSO idle timeout
Roles and Permissions Management	List all permissions
	List all roles
	Update roles
	Create new role
	Delete roles
User Management	Create user endpoint
	Fetch users
	Update user endpoint
	Fetch user by ID
	Delete user endpoint
	Update user password endpoint
	Lock user account
	Unlock user account
Group Management	Fetch groups
	Create group endpoint
	Update group endpoint
	Get group endpoint
	Delete group endpoint
SAML SSO Configuration	List SAML providers
	Create SAML provider endpoint
	Get SAML provider
	Update SAML provider endpoint
	Delete SAML provider endpoint
	List SAML attribute mappers
	Create SAML attribute mapper endpoint
	Delete SAML attribute mapper endpoint
Password Policy	Get password policy
	Update password policy
Microsoft Entra ID Federation Configuration	Get Entra ID configuration endpoint
	Create Entra ID configuration endpoint
	Update Entra ID configuration endpoint
	Delete Entra ID configuration endpoint
	Test Entra ID connection endpoint
	Search Entra ID users endpoint
	Import Entra ID users with roles endpoint
	Search Entra ID groups endpoint
	Search Entra ID group members endpoint
	Import Entra ID groups endpoint

Token Management

The following section lists the commonly used APIs to manage tokens.

Generate token

This API explains how you can generate an access token for authenticating the APIs.

Base URL: https://<FQDN>/pty/<version>/<API>
Path: /login/token
Method: POST

Request Body

loginname: User name for authentication.
password: Password for authentication.

Result

This API returns JWT access token in the response header and the refresh token in the response body. You can use the refresh token in the Refresh token API to obtain new access tokens without logging again.

Sample Request

curl -X 'POST' \
  "https://<FQDN>/pty/v1/auth/login/token" \
  -H "accept: application/json" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'loginname=<User name>&password=<Password>!'

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

{
  "status": 0,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsIn",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.e",
    "expiresIn": 300,
    "refreshExpiresIn": 900
  },
  "messages": []
}

Response header

content-length: 832 
 content-type: application/json 
 date: Thu,16 Oct 2025 10:30:53 GMT 
 pty_access_jwt_token: eyJhbGciOiJSUzI1NiIsInR4YRUw 
 strict-transport-security: max-age=31536000; includeSubDomains

Refresh token

This API explains how to refresh an access token using the refresh token.

Base URL: https://<FQDN>/pty/<version>/<API>
Path: /login/refresh
Method: POST

Request Body

refreshToken: Refresh token for getting a new access token.

Result

This API returns a new JWT access token in the response header and a new refresh token in the response body. You can use this refresh token to obtain new access tokens without logging again.

Sample Request

curl -X 'POST' \
  "https://<FQDN>/pty/v1/auth/login/token/refresh" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "refreshToken": "eyJhbGciOiJIUzUxMiIsInR5cCINGFeZEf8hw"
}
'

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

{
  "status": 0,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiI",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs",
    "expiresIn": 300,
    "refreshExpiresIn": 900
  },
  "messages": []
}

Response header

content-length: 832 
 content-type: application/json 
 date: Thu,16 Oct 2025 10:36:28 GMT 
 pty_access_jwt_token: eyJhbGciOiJSUzI1Nim95VHqh00vHfr8ip9RhyO-4FcxQ 
 strict-transport-security: max-age=31536000; includeSubDomains

Invalidate a user session

This API explains how you can invalidate a user session using the provided refresh token.

Base URL: https://<FQDN>/pty/<version>/<API>
Path: /logout
Method: POST

Request Body

refreshToken: Refresh token for invalidating the user session.

Result

This API invalidates the user session using the refresh token in the Refresh token API.

Sample Request

curl -X 'POST' \
  "https://<FQDN>/pty/v1/auth/logout" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "refreshToken": "eyJhbGciOiJIUzUxMiIsInR5cCIgOiAiSldUOTEifQ."
}'

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

{
  "status": 0,
  "data": {
    "message": "Token invalidated successfully."
  },
  "messages": []
}

Update access token lifespan and SSO idle timeout

This API explains how you can update the access token lifespan and SSO idle timeout.

Base URL: https://<FQDN>/pty/<version>/<API>
Path: /token/lifespan/update
Method: POST

Request Body

accessTokenLifespan: Updated lifespan of the access token in seconds.

Result

This API updates the lifespan of the access token. It also automatically updates the lifespan of the refresh token or the SSO idle timeout by adding 10 minutes to the lifespan of the access token.

Sample Request

curl -X 'POST' \
  "https://<FQDN>/pty/v1/auth/token/lifespan/update" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "accessTokenLifespan": 600
}'

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

"Token lifespan updated successfully."

Roles and Permissions Management

The following section lists the commonly used APIs for managing user roles and permissions.

List all permissions

This API returns a list of all the permissions available/defined in PPC.

Base URL: https://<FQDN>/pty/<version>/<API>
Path: /permissions
Method: GET

Request Body

No parameters.

Result

This API returns a list of all the permissions/roles available/defined in PPC.

Sample Request

curl -X 'GET' \
  "https://<FQDN>/pty/v1/auth/permissions" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>"

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

[
  {
    "name": "user_manager_admin",
    "description": "Permission to manage users with read-write access"
  },
  {
    "name": "saml_viewer",
    "description": "Permission to view SAML configurations with read-only access"
  },
  {
    "name": "user_manager_viewer",
    "description": "Permission to view users with read-only access"
  },
  {
    "name": "cli_access",
    "description": "Grants or restricts a user’s ability to access the CLI"
  },
  {
    "name": "saml_admin",
    "description": "Permission to update SAML configurations with read-write access"
  },
  {
    "name": "group_viewer",
    "description": "Permission to view groups with read-only access"
  },
  {
    "name": "group_admin",
    "description": "Permission to manage groups with read-write access"
  },
  {
    "name": "password_policy_admin",
    "description": "Permission to update password policy with read-write access"
  },
  {
    "name": "insight_viewer",
    "description": "Permission to view Insight Dashboard with read-only access."
  },
  {
    "name": "password_policy_viewer",
    "description": "Permission to view password policy with read-only access"
  },
  {
    "name": "role_viewer",
    "description": "Permission to view roles with read-only access"
  },
  {
    "name": "can_create_token",
    "description": "Permission to create/refresh tokens"
  },
  {
    "name": "insight_admin",
    "description": "Permission to view and edit Insight Dashboard with admin access."
  },
  {
    "name": "role_admin",
    "description": "Permission to manage roles with read-write access"
  },
  {
    "name": "web_admin",
    "description": "Permission to perform all operations available as part of the Web UI."
  }
]

List all roles

This API returns a list of all the roles available/defined in PPC.

Base URL: https://<FQDN>/pty/<version>/<API>
Path: /roles
Method: GET

Request Body

No parameters.

Result

This API returns a list of all the roles available for the logged-in user.

Sample Request

curl -X 'GET' \
  "https://<FQDN>/pty/v1/auth/roles" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>"

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

[
  {
    "name": "directory_administrator",
    "description": "Directory Administrator",
    "composite": true,
    "permissions": [
      "saml_admin", "role_admin", "user_manager_admin", "can_create_token", "password_policy_admin", "group_admin"
    ]
  },
  {
    "name": "directory_viewer",
    "description": "Directory Viewer",
    "composite": true,
    "permissions": [
      "saml_viewer", "password_policy_viewer", "user_manager_viewer", "role_viewer", "group_viewer"
    ]
  },
  {
    "name": "security_administrator",
    "description": "Security Administrator",
    "composite": true,
    "permissions": [
      "can_fetch_package", "role_admin", "web_admin", "cli_access", "saml_admin", "can_export_certificates", "user_manager_admin", "can_create_token", "password_policy_admin", "group_admin", "insight_admin"
    ]
  },
  {
    "name": "security_viewer",
    "description": "Security Administrator Viewer",
    "composite": true,
    "permissions": [
      "saml_viewer", "password_policy_viewer", "insight_viewer", "user_manager_viewer", "role_viewer", "group_viewer"
    ]
  }  
]

Update role

This API enables you to update an existing role and its permissions.

Base URL: https://<FQDN>/pty/<version>/<API>
Path: /roles
Method: PUT

Request Body

name: Role name.
description: Description of the role.
permissions: List of permissions that need to be updated for the existing role.

Result

This API updates the existing role and its permissions.

Sample Request

curl -X 'PUT' \
  "https://<FQDN>/pty/v1/auth/roles" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "admin",
  "description": "Administrator role",
  "permissions": [
    "perm1",
    "perm2"
  ]
}'

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

{
  "role_name": "admin",
  "status": "updated"
}

Create role

This API enables you to create a role.

Base URL: https://<FQDN>/pty/<version>/<API>
Path: /roles
Method: POST

Request Body

name: Role name.
description: Description of the role.
permissions: List of permissions that need to created for the existing role.

Result

This API creates a roles with the requested permissions.

Sample Request

curl -X 'POST' \
  "https://<FQDN>/pty/v1/auth/roles" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "admin",
  "description": "Administrator role",
  "permissions": [
    "perm1",
    "perm2"
  ]
}'

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

{
  "role_name": "admin",
  "status": "created"
}

Delete role

This API enables you to delete a role.

Base URL: https://<FQDN>/pty/<version>/<API>
Path: /roles
Method: DELETE

Request Body

name: Role name.

Result

This API deletes the specific role.

Sample Request

curl -X 'POST' \
  "https://<FQDN>/pty/v1/auth/roles" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "admin"
}'

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

{
  "role_name": "admin",
  "status": "deleted"
}

User Management

The following section lists the commonly used APIs for managing users.

Create user endpoint

This API enables you to create a user.

Base URL: https://<FQDN>/pty/<version>/<API>
Path: /users
Method: POST

Request Body

username: Name of the user. This is a mandatory field
email: Email of the user.
firstName: First name of the user.
lastName: Last name of the user.
enabled: Enable the user.
password: Password for the user.
roles: Roles to be assigned to the user.
groups: Groups in which the user is included.
identityProviders: An optional array that lists the SAML provider aliases to link the user, for example, AWS-IDP or AZURE-IDP, configured as part of the SAML SSO configuration.

Result

This API creates a user with a unique user ID.

Sample Request

{
  "username": "alpha",
  "email": "alpha@example.com",
  "firstName": "Alpha",
  "lastName": "User",
  "password": "StrongPassword123!",
  "roles": [
    "directory_admin"
  ],
  "groups": [
    "framework"
  ],
  "identityProviders": {
    "AWS-IDP": {
      "userId": "alpha@example.com",
      "userName": "alpha@example.com"
    }
  }
}

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

{
  "user_id": "7636708c-c714-4e8e-a3e6-f5fc6c49f9c0",
  "username": "alpha"
}

Fetch users

This API enables you to retrieve the user details.

Base URL: https://<FQDN>/pty/<version>/<API>
Path: /users
Method: GET

Request Body

No parameters.

Query Parameters

max: Maximum number of entries that can retrieved.
first: Number of entries that can be skipped from the start of the data. For example, if you specify the value as 4, then the first four entries will be skipped from the result.

Result

This API retrieves a list of users.

Sample Request

curl -X 'GET' \
  "https://<FQDN>/pty/v1/auth/users?max=100&first=0" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>"

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

[
  {
    "username": "admin",
    "email": "admin@example.com",
    "firstName": "Admin",
    "lastName": "User",
    "enabled": true,
    "id": "71c573a0-7412-475d-be67-4bf6fdf71404",
    "createdTimestamp": null,
    "attributes": null,
    "emailVerified": true
  },
  {
    "username": "alpha",
    "email": "alpha@example.com",
    "firstName": "Alpha",
    "lastName": "User",
    "enabled": true,
    "id": "7636708c-c714-4e8e-a3e6-f5fc6c49f9c0",
    "createdTimestamp": 1760643896108,
    "attributes": null,
    "emailVerified": false
  },
  {
    "username": "dfuser",
    "email": null,
    "firstName": "se",
    "lastName": "se",
    "enabled": false,
    "id": "12770ab4-d3a0-4243-8018-5bb1fb0d06d7",
    "createdTimestamp": 1760425034931,
    "attributes": null,
    "emailVerified": false
  },
  {
    "username": "fds",
    "email": null,
    "firstName": "dsf",
    "lastName": "fs",
    "enabled": false,
    "id": "a1251ca4-664d-469a-b1c1-539fe8c73a9d",
    "createdTimestamp": 1760425052196,
    "attributes": null,
    "emailVerified": false
  },
  {
    "username": "shiva",
    "email": "shiva.v@protegrity.com",
    "firstName": "shiva",
    "lastName": "v",
    "enabled": true,
    "id": "0743b449-c050-4e49-ba95-974cd2069a84",
    "createdTimestamp": 1760433609089,
    "attributes": null,
    "emailVerified": false
  },
  {
    "username": "testuser1",
    "email": null,
    "firstName": "t",
    "lastName": "tes",
    "enabled": true,
    "id": "948c1484-45d7-4df9-aea4-9534ca2d1923",
    "createdTimestamp": 1760424968139,
    "attributes": null,
    "emailVerified": false
  },
  {
    "username": "testuser2",
    "email": null,
    "firstName": "sdf",
    "lastName": "df",
    "enabled": true,
    "id": "d4961126-d324-4166-97e6-2fac1f40566a",
    "createdTimestamp": 1760425012482,
    "attributes": null,
    "emailVerified": false
  }
]

Update user endpoint

This API enables you to update the details of an user.

Base URL: https://<FQDN>/pty/<version>/<API>
Path: /users
Method: PUT

Request Body

id: ID of the user. This is a mandatory field
email: Email of the user.
firstName: First name of the user.
lastName: Last name of the user.
enabled: Enable the user.
password: Password for the user.
roles: Roles to be assigned to the user.
groups: Groups in which the user is included.
identityProviders: An optional array that lists the SAML provider aliases to link the user, for example, AWS-IDP or AZURE-IDP, configured as part of the SAML SSO configuration.

Result

This API updates the user details.

Sample Request

{
  "username": "alpha",
  "email": "alpha@example.com",
  "firstName": "Alpha",
  "lastName": "User",
  "password": "StrongPassword123!",
  "roles": [
    "directory_admin"
  ],
  "groups": [
    "framework"
  ],
  "identityProviders": {
    "AWS-IDP": {
      "userId": "alpha@example.com",
      "userName": "alpha@example.com"
    }
  }
}

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

{
  "status": "updated",
  "userId": "7636708c-c714-4e8e-a3e6-f5fc6c49f9c0"
}

Fetch User by Id

This API enables you to fetch the details of a specific user by specifying the user ID.

Base URL: https://<FQDN>/pty/<version>/<API>
Path: /users/{user_id}
Method: GET

Request Body

No parameters.

Path Parameters

user_id: Unique ID of the user. This is a mandatory field.

Result

This API retrieves the details of the specific user.

Sample Request

curl -X 'GET' \
  "https://<FQDN>/pty/v1/auth/users/7636708c-c714-4e8e-a3e6-f5fc6c49f9c0" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>"

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

{
  "id": "7636708c-c714-4e8e-a3e6-f5fc6c49f9c0",
  "username": "alpha",
  "firstName": "lpha",
  "lastName": "User",
  "email": "alpha@example.com",
  "emailVerified": false,
  "enabled": true,
  "createdTimestamp": 1760643896108,
  "groups": [],
  "roles": [
    "directory_admin"
  ]
}

Delete user endpoint

This API enables you to delete a user.

Base URL: https://<FQDN>/pty/<version>/<API>
Path: /users/{user_id}
Method: DELETE

Request Body

No parameters.

Path Parameters

user_id: Unique ID of the user. This is a mandatory field.

Result

This API deletes the specified user.

Sample Request

curl -X 'DELETE' \
  "https://<FQDN>/pty/v1/auth/users/7636708c-c714-4e8e-a3e6-f5fc6c49f9c0" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>"
}'

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

{
  "status": "deleted",
  "user_id": "7636708c-c714-4e8e-a3e6-f5fc6c49f9c0"
}

Update user password endpoint

This API enables you to update the password of an existing user.

Base URL: https://<FQDN>/pty/<version>/<API>
Path: /users/{user_id}/password
Method: PUT

Request Body

{
  "newPassword": "NewStrongPassword123!",
  "oldPassword": "OldPassword123!"
}

Path Parameters

user_id: Unique ID of the user. This is a mandatory field.

Result

This API creates a roles with the requested permissions.

Sample Request

curl -X 'PUT' \
  "https://<FQDN>/pty/v1/auth/users/password" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
  "userId": "7636708c-c714-4e8e-a3e6-f5fc6c49f9c0",
  "newPassword": "NewStrongPassword123!",
  "temporary": false
}'

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

{
  "status": "password_updated",
  "userId": "7636708c-c714-4e8e-a3e6-f5fc6c49f9c0",
  "temporary": false
}

Lock user account

This API enables you to lock the user account.

Base URL: https://<FQDN>/pty/<version>/<API>
Path: /users/{user_id}/lock
Method: PUT

Request Body

No parameters.

Path Parameters

user_id: Unique ID of the user. This is a mandatory field.

Result

This API locks the user.

Sample Request

curl -X 'PUT' \
  "https://<FQDN>/pty/v1/auth/users/94070ecb-8639-41f4-b3e1-fda5cc7f8888/lock" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>"
}'

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

{
  "status": "locked",
  "user_id": "260e89e5-f77a-4aad-b733-22ca5c7c34a8"
}

unlock user account

This API enables you to unlock an existing user.

Base URL: https://<FQDN>/pty/<version>/<API>
Path: /users/password
Method: PUT

Request Body

password: Password for the user.

Path Parameters

user_id: Unique ID of the user. This is a mandatory field.

Result

This API unlocks the user.

Sample Request

curl -X 'PUT' \
  "https://<FQDN>/pty/v1/auth/users/94070ecb-8639-41f4-b3e1-fda5cc7f8888/unlock" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
  "password": "StrongPasword123!"
}'

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

{
  "status": "unlocked",
  "user_id": "260e89e5-f77a-4aad-b733-22ca5c7c34a8",
  "password_temporary": true
}

Group Management

The following section lists the commonly used APIs for managing groups.

Fetch groups

This API enables you retrieve a list of all the groups.

Base URL: https://<FQDN>/pty/<version>/<API>
Path: /groups
Method: GET

Request Body

No parameters.

Query Parameters

max: Maximum number of entries that can be retrieved.
first: Number of entries that can be skipped from the start of the data. For example, if you specify the value as 4, then the first four entries will be skipped from the result.

Result

This API a list of the available groups.

Sample Request

curl -X 'GET' \
  "https://<FQDN>/pty/v1/auth/groups?max=100&first=0" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>"

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

[
  {
    "id": "d93f9953-b016-4db3-b786-4d4402997ac1",
    "name": "<group_name>",
    "description": "<group_description>",
    "attributes": {
      "groupType": [
        "local"
      ]
    },
    "members": [
      "member1",
      "member2"
    ],
    "roles": [
      "security_administrator"
    ]
  }
]

Create group endpoint

This API enables you create a group.

Base URL: https://<FQDN>/pty/<version>/<API>
Path: /groups
Method: POST

Request Body

name: Name of the group. This is a mandatory field.
description: Description of the group.
members: List of user names that need to be added as members.
roles: List of role names that need to be assigned to the group.

Result

This API creates a group with the specified members and roles.

Sample Request

curl -X 'POST' \
  "https://<FQDN>/pty/v1/auth/groups" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "developers",
  "description": "",
  "members": [
    "testuser1",
    "testuser2"
  ],
  "roles": [
    "service_admin",
    "user_manager"
  ]
}'

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

{ “group_id”: “aee4c370-4e97-4b55-a072-0840fe83a2aa”, “name”: “developers”, “status”: “created”, “members_added”: 2, “roles_assigned”: 2 }

Update group endpoint

This API enables you update an existing group.

Base URL: https://<FQDN>/pty/<version>/<API>
Path: /groups
Method: PUT

Request Body

group_id: Unique ID of the group. This is a mandatory field.
members: Members added to the group.
roles: Roles assigned to the group.

Result

This API updates the existing role and its permissions.

Sample Request

curl -X 'PUT' \
  "https://<FQDN>/pty/v1/auth/groups" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
  "group_id": "group-uuid",
  "members": [
    "testuser2"
  ],
  "roles": [
    "service_admin"
  ]
}'

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

{
  "status": "updated",
  "group_id": "d93f9953-b016-4db3-b786-4d4402997ac1",
  "members_updated": 1,
  "roles_updated": 1,
  "identity_providers_updated": null
}

Get group endpoint

This API enables you to get specific information by group ID.

Base URL: https://<FQDN>/pty/<version>/<API>
Path: /groups/{group_id}
Method: GET

Request Body

No parameters.

Path Parameters

group_id: ID of the group that needs to be retrieved. This is a mandatory field.

Result

This API retrieves the details of the specified group.

Sample Request

curl -X 'GET' \
  "https://<FQDN>/pty/v1/auth/groups/aee4c370-4e97-4b55-a072-0840fe83a2aa" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>"

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

{
  "id": "aee4c370-4e97-4b55-a072-0840fe83a2aa",
  "name": "developers",
  "description": "",
  "attributes": {
    "groupType": [
      "local"
    ]
  },
  "members": [
    "john.doe",
    "jane.smith"
  ],
  "roles": [
    "service_admin",
    "directory_admin"
  ]
}

Delete groupend point

This API enables you to delete an existing group.

Base URL: https://<FQDN>/pty/<version>/<API>
Path: /groups/{group_id}
Method: DELETE

Request Body

No parameters.

Path Parameters

group_id: ID of the group that needs to be deleted. This is a mandatory field.

Result

This API deletes the specified group.

Sample Request

curl -X 'DELETE' \
  "https://<FQDN>/pty/v1/auth/groups/aee4c370-4e97-4b55-a072-0840fe83a2aa" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>"
  -d '{
  "deleteMembers":false
  }'

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

{
  "status": "deleted",
  "group_id": "aee4c370-4e97-4b55-a072-0840fe83a2aa"
}

SAML SSO Configuration

The following section lists the commonly used APIs for managing SAML providers.

List SAML providers

This API enables you to list the existing SAML providers.

Base URL: https://<FQDN>/pty/<version>/<API>
Path: /saml/providers
Method: GET

Request Body

No parameters

Result

This API retrieves a list of the existing SAML providers.

Sample Request

curl -X 'GET' \
  "https://<FQDN>/pty/v1/auth/saml/providers" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>"

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

[
{
  "alias": "azuread",
  "displayName": "Protegrity SAML SSO  (Azure AD IDP)",
  "providerId": "saml",
  "enabled": false,
  "config": {
    "postBindingLogout": "false",
    "singleLogoutServiceUrl": "https://login.microsoftonline.com/c3ebfd9e-ec7b-4ab3-a13f-915e941a2785/saml2",
    "postBindingResponse": "true",
    "backchannelSupported": "false",
    "caseSensitiveOriginalUsername": "false",
    "encryptionAlgorithm": "RSA-OAEP",
    "xmlSigKeyInfoKeyNameTransformer": "KEY_ID",
    "idpEntityId": "https://sts.windows.net/c3ebfd9e-ec7b-4ab3-a13f-915e941a2785/",
    "useMetadataDescriptorUrl": "false",
    "loginHint": "false",
    "allowCreate": "true",
    "enabledFromMetadata": "true",
    "syncMode": "LEGACY",
    "authnContextComparisonType": "exact",
    "singleSignOnServiceUrl": "https://login.microsoftonline.com/c3ebfd9e-ec7b-4ab3-a13f-915e941a2785/saml2",
    "wantAuthnRequestsSigned": "true",
    "allowedClockSkew": "0",
    "artifactBindingResponse": "false",
    "validateSignature": "true",
    "nameIDPolicyFormat": "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",
    "entityId": "https://<FQDN>/mysamlapp/saml/metadata",
    "signSpMetadata": "true",
    "wantAssertionsEncrypted": "false",
    "signatureAlgorithm": "RSA_SHA256",
    "sendClientIdOnLogout": "false",
    "wantAssertionsSigned": "false",
    "metadataDescriptorUrl": "https://login.microsoftonline.com/c3ebfd9e-ec7b-4ab3-a13f-915e941a2785/federationmetadata/2007-06/federationmetadata.xml?appid=967110c7-a06b-432e-ad40-47859837a76c",
    "sendIdTokenOnLogout": "true",
    "postBindingAuthnRequest": "true",
    "forceAuthn": "false",
    "attributeConsumingServiceIndex": "0",
    "addExtensionsElementWithKeyInfo": "false",
    "principalType": "SUBJECT"
  }
},
{
  "alias": "azured",
  "displayName": "Protegrity 2 SAML SSO  (Azure AD IDP)",
  "providerId": "saml",
  "enabled": true,
  "config": {
    "postBindingLogout": "false",
    "singleLogoutServiceUrl": "https://login.microsoftonline.com/c3ebfd9e-ec7b-4ab3-a13f-915e941a2785/saml2",
    "postBindingResponse": "true",
    "backchannelSupported": "false",
    "caseSensitiveOriginalUsername": "false",
    "xmlSigKeyInfoKeyNameTransformer": "KEY_ID",
    "idpEntityId": "https://sts.windows.net/c3ebfd9e-ec7b-4ab3-a13f-915e941a2785/",
    "useMetadataDescriptorUrl": "false",
    "loginHint": "false",
    "allowCreate": "true",
    "enabledFromMetadata": "true",
    "syncMode": "LEGACY",
    "authnContextComparisonType": "exact",
    "singleSignOnServiceUrl": "https://login.microsoftonline.com/c3ebfd9e-ec7b-4ab3-a13f-915e941a2785/saml2",
    "wantAuthnRequestsSigned": "true",
    "allowedClockSkew": "0",
    "guiOrder": "0",
    "artifactBindingResponse": "false",
    "validateSignature": "true",
    "signingCertificate": "MIIC8DCCAdigAwIBAgIQf++2tyNO+YtIpa4MDh1hiQcoVX",
    "nameIDPolicyFormat": "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",
    "entityId": "https://<FQDN>/mysamlapp/saml/metadata",
    "signSpMetadata": "true",
    "wantAssertionsEncrypted": "false",
    "signatureAlgorithm": "RSA_SHA256",
    "sendClientIdOnLogout": "false",
    "wantAssertionsSigned": "false",
    "metadataDescriptorUrl": "https://login.microsoftonline.com/c3ebfd9e-ec7b-4ab3-a13f-915e941a2785/federationmetadata/2007-06/federationmetadata.xml?appid=967110c7-a06b-432e-ad40-47859837a76c",
    "sendIdTokenOnLogout": "true",
    "postBindingAuthnRequest": "true",
    "forceAuthn": "false",
    "attributeConsumingServiceIndex": "0",
    "addExtensionsElementWithKeyInfo": "false",
    "principalType": "SUBJECT"
  }
}
]

Create SAML provider endpoint

This API enables you to create a SAML provider configuration.

Base URL: https://<FQDN>/pty/<version>/<API>
Path: /saml/providers
Method: POST

Request Body

alias: Unique alias for the SAML provider. This is a mandatory field.
displayName: Display name for the SAML provider that will appear on the login page. This is a mandatory field.
configType: Configuration type, either metadata URL or metadata file content. This is a mandatory field.
metadataUrl: URL to fetch the SAML metadata from the identity provider. For example, https://login.microsoftonline.com/tenant-id/federationmetadata/2007-06/federationmetadata.xml.
metadataFileContent: SAML metadata XML content as a string. For example, <?xml version=\"1.0\"?>...</EntityDescriptor>.
signingCertificate: X.509 certificate for signing SAML requests. Use the PEM format without the headers.
nameIdPolicyFormat: NameID policy format for SAML authentication. For example, urn:oasis:names:tc:SAML:2.0:nameid-format:persistent.
forceAuthn: Force re-authentication of the user even if the user is already authenticated.
validateSignature: Validate the SAML response and assertion signatures.
wantAssertionsSigned: Require the SAML assertions to be signed.
wantAssertionsEncrypted: Require the SAML assertions to be encrypted.
signatureAlgorithm: Signature algorithm for SAML requests. For example, RSA_SHA256.
attributeMapping: Mapping of SAML attributes to user attributes.
enabled: Enable or disable the SAML provider.

For details of the each parameter, refer the documentation for the corresponding SAML provider.

Result

This API enables you to add a SAML provider.

Sample Request

{
  "alias": "azure-ad-saml",
  "configType": "metadataUrl",
  "displayName": "Azure AD SAML",
  "enabled": true,
  "forceAuthn": false,
  "metadataUrl": "https://login.microsoftonline.com/tenant-id/federationmetadata/2007-06/federationmetadata.xml",
  "serviceProviderEntityId": "my-service-provider"
}

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

{ “status”: “created”, “alias”: “test-azure-ad-saml”, “configType”: “metadataUrl”, “message”: “SAML provider created successfully from metadata” }

Note: The metadataFileContent parameter is not supported. You cannot upload or copy the metadata file. Instead, use the metadataUrl option to configure SAML.

Get SAML provider

This API enables you retrieve the details of a specific SAML provider.

Base URL: https://<FQDN>/pty/<version>/<API>
Path: /providers/{alias}
Method: GET

Request Body

No parameters.

Path Parameters

alias: Alias of the SAML provider. This is a mandatory field.

Result

This API retrieves the details about the specific SAML provider.

Sample Request

curl -X 'GET' \
  "https://<FQDN>/pty/v1/auth/saml/providers/azure-ad-saml" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>"

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

{
  "alias": "azure-ad-saml",
  "displayName": "Azure AD SAML",
  "providerId": "saml",
  "enabled": true,
  "config": {
    "additionalProp1": {}
  }
}

Update SAML provider endpoint

This API enables you update the configurations of an existing SAML provider.

Base URL: https://<FQDN>/pty/<version>/<API>
Path: /providers/{alias}
Method: PUT

Request Body

No parameters.

Path Parameters

alias: Alias of the SAML provider that you want to update. This is a mandatory field.

Result

This API updates the existing SAML provider.

Sample Request


{
  "alias": "azure-ad-saml",
  "configType": "metadataUrl",
  "displayName": "Azure AD SAML",
  "enabled": true,
  "forceAuthn": false,
  "metadataUrl": "https://login.microsoftonline.com/tenant-id/federationmetadata/2007-06/federationmetadata.xml",
  "serviceProviderEntityId": "my-service-provider"
}

Note: The metadataFileContent parameter is not supported. You cannot upload or copy the metadata file. Instead, use the metadataUrl option to configure SAML.

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

{ “status”: “updated”, “alias”: “azure-ad-saml” }

Delete SAML provider endpoint

This API enables you to delete the configuration of an existing SAML provider.

Base URL: https://<FQDN>/pty/<version>/<API>
Path: /saml/providers/{alias}
Method: DELETE

Request Body

No parameters.

Path Parameters

alias: Alias of the SAML provider that you want to delete. This is a mandatory field.

Result

This API deletes the SAML provider.

Sample Request

curl -X 'DELETE' \
  "https://<FQDN>/pty/v1/auth/saml/providers/azure-ad-saml" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>"

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

{
  "status": "deleted",
  "alias": "azure-ad-saml"
}

List SAML attribute mappers

This API enables you to list all attribute mappers for a SAML provider.

Base URL: https://<FQDN>/pty/<version>/<API>
Path: /saml/providers/{alias}
Method: GET

Request Body

No parameters.

Path Parameters

alias: Alias of the SAML provider that you want to list. This is a mandatory field.

Result

This API lists all attribute mappers for a SAML provider.

Sample Request

curl -X 'GET' \
  "https://&lt;FQDN&gt;/pty/v1/auth/saml/providers/azure-ad-saml/mappers" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>"

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

[
  {
    "id": "mapper-uuid",
    "name": "email-mapper",
    "identityProviderMapper": "saml-user-attribute-idp-mapper",
    "identityProviderAlias": "azure-ad-saml",
    "config": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    }
  }
]

Create SAML Attribute Mappers Endpoint

This API enables you to create attribute mappers for a SAML provider.

Base URL: https://<FQDN>/pty/<version>/<API>
Path: /saml/providers/{alias}
Method: POST

Request Body

No parameters.

Path Parameters

alias: Alias of the SAML provider that you want to list. This is a mandatory field.

Result

This API lists all attribute mappers for a SAML provider.

Sample Request

{
  "attributeName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
  "mapperType": "saml-user-attribute-idp-mapper",
  "name": "email-mapper",
  "syncMode": "INHERIT",
  "userAttribute": "email"
}

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

{
  "message": "Attribute mapper created successfully",
  "mapperId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Delete SAML Attribute Mappers Endpoint

This API delete an attribute mappers for a SAML provider.

Base URL: https://<FQDN>/pty/<version>/<API>
Path: /saml/providers/{alias}
Method: DELETE

Request Body

No parameters.

Path Parameters

alias: Alias of the SAML provider that you want to list. This is a mandatory field.
mapper_id:

Result

This API deletes all attribute mappers for a SAML provider.

Sample Request

curl -X 'DELETE' \
  "https://&lt;FQDN&gt;/pty/v1/auth/saml/providers/azure-ad-saml/mappers/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>"

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

{
  "status": "deleted",
  "mapperId": "mapper-uuid",
  "alias": "azure-ad-saml"
}

Password Policy

The following section lists the commonly used APIs for managing Password Policy.

Get Password Policy

This API allows you to get current password policy configuration.

Base URL: https://<FQDN>/pty/<version>/<API>
Path: /passwordpolicy
Method: GET

Request Body

No parameters.

Path Parameters

No parameters.

Result

This API gets current password policy configuration.

Sample Request

curl -X 'GET' \
  "https://&lt;FQDN&gt;/pty/v1/auth/passwordpolicy" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access token>"

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

{
  "policy": {
    "digits": 1,
    "forceExpiredPasswordChange": 365,
    "hashAlgorithm": "pbkdf2-sha256",
    "hashIterations": 27500,
    "length": 8,
    "lowerCase": 1,
    "maxAuthAge": 3600,
    "maxLength": 64,
    "notContainsUsername": true,
    "notEmail": true,
    "notUsername": true,
    "passwordAge": 365,
    "passwordHistory": 3,
    "recoveryCodesWarningThreshold": 3,
    "regexPattern": "^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d).*$",
    "specialChars": 1,
    "upperCase": 1
  }
}

Update Password Policy

This API allows you to update password policy configuration.

Base URL: https://<FQDN>/pty/<version>/<API>
Path: /passwordpolicy
Method: PUT

Request Body

No parameters.

Path Parameters

No parameters.

Result

This API updates the password policy configuration.

Sample Request

{
  "policy": {
    "digits": 2,
    "forceExpiredPasswordChange": 90,
    "length": 10,
    "lowerCase": 1,
    "notUsername": true,
    "passwordHistory": 5,
    "specialChars": 1,
    "upperCase": 1
  }
}

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

{
  "policy": {
    "digits": 1,
    "forceExpiredPasswordChange": 365,
    "hashAlgorithm": "pbkdf2-sha256",
    "hashIterations": 27500,
    "length": 8,
    "lowerCase": 1,
    "maxAuthAge": 3600,
    "maxLength": 64,
    "notContainsUsername": true,
    "notEmail": true,
    "notUsername": true,
    "passwordAge": 365,
    "passwordHistory": 3,
    "recoveryCodesWarningThreshold": 3,
    "regexPattern": "^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d).*$",
    "specialChars": 1,
    "upperCase": 1
  }
}

Microsoft Entra ID Federation Configuration

Microsoft Entra ID is a cloud-based identity and access management service. It manages your cloud and on-premise applications and protects user identities and credentials. The following section lists the commonly used APIs for managing Microsoft Entra ID federation.

Get Entra ID configuration endpoint

This API enables you to list the current Entra ID configuration.

Base URL: https://<FQDN>/pty/<version>/<API>
Path: /federation/entra/config
Method: GET

Request Body

No parameters

Result

This API retrieves the current Entra ID configuration.

Sample Request

curl -X 'GET' \
  "https://<FQDN>/pty/v1/auth/federation/entra/config" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>"

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

{
"tenantId": "<Tenant_ID>",
"clientId": "<Client_ID>",
"enabled": true,
"createdAt": "2026-01-16T11:02:43.259928",
"updatedAt": "2026-01-20T13:26:41.303308"
}

Create Entra ID configuration endpoint

This API enables you to create an Entra ID configuration.

Base URL: https://<FQDN>/pty/<version>/<API>
Path: /federation/entra/config
Method: POST

Request Body

tenantID: Entra ID tenant ID.
clientID: Entra ID application ID.
clientSecret: Entra ID application client secret.
enabled: Whether Entra ID configuration is enabled.

Result

This API creates an Entra ID configuration.

Sample Request

curl -X 'POST' \
  "https://<FQDN>/pty/v1/auth/federation/entra/config" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>"\
  -H "Content-Type: application/json" \
  -d '{
  "tenantId": "<Tenant_ID>",
  "clientId": "<Client_ID>",
  "clientSecret": "<Kubernetes_client_secret>",
  "enabled": true
}'

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 201, if the API is invoked successfully.

Response body

{
"status": "created",
"message": "string",
"config": {
  "tenantId": "<Tenant_ID>",
  "clientId": "CLient_ID",
  "enabled": true,
  "createdAt": "2026-01-16T11:02:43.259928",
  "updatedAt": "2026-01-20T13:26:41.303308"
}
}

Update Entra ID configuration endpoint

This API enables you to update the Entra ID configuration.

Base URL: https://<FQDN>/pty/<version>/<API>
Path: /federation/entra/config
Method: PUT

Request Body

tenantID: Entra ID tenant ID.
clientID: Entra ID application ID.
clientSecret: Entra ID application client secret.
enabled: Whether Entra ID configuration is enabled. It can have one of the following values:
- true: Entra ID configuration is enabled.
- false: Entra ID configuration is not enabled.

Result

This API updates the current Entra ID configuration.

Sample Request

curl -X 'PUT' \
  "https://<FQDN>/pty/v1/auth/federation/entra/config" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>"\
  -H "Content-Type: application/json" \
  -d '{
  "clientId": "r1290385-00eb-43d4-b452-e4dc25b55c54",
  "clientSecret": "ADC7Q~-PXz3kthHgldpNXLcBoYy_L0rTWRn2facz",
  "enabled": true,
  "tenantId": "2e56943b-6c92-446a-81b4-ead9ab5c5e0c"
}
'

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 201, if the API is invoked successfully.

Response body

{
"status": "created",
"message": "Entra ID configuration created successfully",
"config": {
  "tenantId": "2e56943b-6c92-446a-81b4-ead9ab5c5e0c",
  "clientId": "r1290385-00eb-43d4-b452-e4dc25b55c54",
  "enabled": true,
  "createdAt": "2026-02-03T09:56:20.244693",
  "updatedAt": "2026-02-03T09:56:20.244865"
}
}

Delete Entra ID configuration endpoint

This API enables you to delete an Entra ID configuration.

Base URL: https://<FQDN>/pty/<version>/<API>
Path: /federation/entra/config
Method: DELETE

Request Body

No parameters

Result

This API deletes a Microsoft Entra ID configuration.

Sample Request

curl -X 'DELETE' \
  "https://<FQDN>/pty/v1/auth/federation/entra/config" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>"

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

{
"status": "deleted",
"message": "Entra ID configuration deleted successfully"
}

Test Entra ID connection endpoint

This API enables you to test an Entra ID connection endpoint.

Base URL: https://<FQDN>/pty/<version>/<API>
Path: /federation/entra/config/test
Method: POST

Request Body

tenantID: Entra ID tenant ID.
clientID: Entra ID application ID.
clientSecret: Entra ID application client secret.
useStoredConfig: Specify true to test the currently stored configuration. Speicify false to provide credentials for testing without storing.

Result

This API tests an Entra ID endpoint connection.

Sample Request

curl -X 'POST' \
  "https://<FQDN>/pty/v1/auth/federation/entra/config/test" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
  "tenantId": "<Tenant_ID>",
  "clientId": "<Client_ID>",
  "clientSecret": "<Client_secret>",
  "useStoredConfig": false
}'

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

{
"status": "success",
"message": "string",
"tenantId": "<Tenant_ID>",
"userCount": 0,
"testTimestamp": "2026-01-20T13:26:41.303308"
}

Search Entra ID users endpoint

This API enables you to search Entra ID users using the stored configuration.

Base URL: https://<FQDN>/pty/<version>/<API>
Path: /federation/entra/users/search
Method: POST

Request Body

searchQuery: Specify the name of the Entra ID user to search for specific users. Specify null to retrieve a list of all the Entra ID users.

Query Parameters

max: Maximum number of entries that can retrieved.
first: Number of entries that can be skipped from the start of the data. For example, if you specify the value as 4, then the first four entries will be skipped from the result.

Result

This API searches Entra ID users.

Sample Request

curl -X 'POST' \
  "https://<FQDN>/pty/v1/auth/federation/entra/users/search?max=100&first=0" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
  "searchQuery": "john"
}'

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

{
"status": "success",
"message": "Found 1 users matching 'john'",
"users": [
  {
    "userPrincipalName": "John", 
   "email": "john.doe@protegrity.com", 
    "firstName": "John", 
    "lastName": "Doe"
  }
],
"totalCount": 1,
"searchTimestamp": "2026-02-03T10:03:48.722709"
}

Import Entra ID users with roles endpoint

This API enables you to import Entra ID users with assigned roles.

Base URL: https://<FQDN>/pty/<version>/<API>
Path: /federation/entra/users
Method: POST

Request Body

users: Array of user objects to import. Each user must have either the userPrincipalName or email parameter specified.
- userPrincipalName: User principal name from Entra ID.
- email: Primary email address of the user.
- firstName: First name of the user. This is an optional parameter.
- lastName: Last name of the user. This is an optional parameter.
- roles: An array that specifies the roles assigned to the user.
- identityProviders: An array that specifies the identity providers to be associated with the user. This is an optional field. For example, you can specify the value as AWS-IDP or AZURE-IDP.
dryRun: If true, validates the import without actually creating users. The default value is false.

Result

This API imports Entra ID users with assigned roles.

Sample Request

curl -X 'POST' \
  "https://<FQDN>/pty/v1/auth/federation/entra/users" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "users": [
        {
            "userPrincipalName": "admin@company.com",
            "email": "admin@company.com",
            "firstName": "Admin",
            "lastName": "User",
            "roles": ["administrator", "user"],
            "identityProviders": ["AWS-IDP"]
        },
        {
            "userPrincipalName": "user@company.com",
            "email": "user@company.com",
            "firstName": "Regular",
            "lastName": "User",
            "roles": ["user"]
        }
    ],
    "dryRun": true
}'

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 201, if the API is invoked successfully.

Response body

{
"status": "success",
"message": "Users imported successfully",
"totalUsers": 10,
"successCount": 9,
"failedCount": 1
}

Search Entra ID groups endpoint

This API enables you to search for Entra ID groups using stored configuration.

Base URL: https://<FQDN>/pty/<version>/<API>
Path: /federation/entra/groups/search
Method: POST

Request Body

searchQuery: Specify the name of the Entra ID group to search for specific groups. Specify null to retrieve a list of all the Entra ID groups.

Query Parameters

max: Maximum number of entries that can retrieved.
first: Number of entries that can be skipped from the start of the data. For example, if you specify the value as 4, then the first four entries will be skipped from the result.

Result

This API searches for Entra ID groups.

Sample Request

curl -X 'POST' \
  "https://<FQDN>/pty/v1/auth/federation/entra/groups/search" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
  "searchQuery": "admin"
}'

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

{
"status": "success",
"message": "string",
"groups": [
  {
    "id": "1",
    "displayName": "admin"
  }
],
"totalCount": 0,
"searchTimestamp": "2026-01-20T13:26:41.303308"
}

Search Entra ID group members endpoint

This API enables you to search for Entra ID group members using stored configuration.

Base URL: https://<FQDN>/pty/<version>/<API>
Path: /federation/entra/groups/members/search
Method: POST

Request Body

groupID: ID of the searched group. This value is case-sensitive and must be an exact match.
searchQuery: Specify the name of the Entra ID group member to search for a specific member. If this parameter is not specified, then the API retrieve a list of all the members of the Entra ID group.

Result

This API searches for Entra ID group members.

Sample Request

curl -X 'POST' \
  "https://<FQDN>/pty/v1/auth/federation/entra/groups/members/search" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
  "groupId": "12345678-1234-1234-1234-123456789012",
  "searchQuery": "john"
}'

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 200, if the API is invoked successfully.

Response body

{
"status": "success",
"message": "string",
"groupId": "12345678-1234-1234-1234-123456789012",
"groupName": "admin",
"members": [
  {
    "userPrincipalName": "John",
    "email": "john.doe@protegrity.com",
    "firstName": "John",
    "lastName": "Doe"
  }
],
"totalCount": 0,
"searchTimestamp": "2026-01-20T13:26:41.303308"
}

Import Entra ID groups endpoint

This API enables you to import Entra ID groups into the application.

Base URL: https://<FQDN>/pty/<version>/<API>
Path: /federation/entra/groups
Method: POST

Request Body

groups: Array of group objects to import. Each user must have the id or displayName parameters specified.
- id: Unique group identifier from Entra ID. This is a required field.
- displayName: Group display name. This is a required field.
- description: Group description.
- importMembers: Specify true to import group members. The default value is false.
- memberRoles: An array that specifies the roles assigned to group members.
- identityProviders: An array that specifies the identity providers to be associated with the group. This is an optional field. For example, you can specify the value as AWS-IDP or AZURE-IDP.
dryRun: If true, validates the import without actually creating users. The default value is false.

Result

This API imports Entra ID groups.

Sample Request

curl -X 'POST' \
  "https://<FQDN>/pty/v1/auth/federation/entra/groups" \
  -H "accept: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
  "groups": [
    {
      "id": "12345678-1234-1234-1234-123456789012",
      "displayName": "Administrators",
      "description": "Administrative users group",
      "importMembers": true,
      "memberRoles": [
        "user",
        "member"
      ],
      "identityProviders": ["AWS-IDP"]
    }
  ],
  "dryRun": true
}'

This sample request uses the access token of the logged-in user for authentication.
For more information about generating the access token, refer to the section Generate token.

Sample Response

The following response appears for the status code 201, if the API is invoked successfully.

Response body

{
"status": "success",
"message": "Groups imported successfully",
"totalGroups": 5,
"successCount": 5,
"totalMembersImported": 25
}

Feedback

Was this page helpful?

Last modified : April 13, 2026