Excalibur v4 REST API documentation 4.18.0¶

Version: 4.18.0 (February 2025)

Documentation and specifications:

The Swagger definition provides a detailed, interactive reference for all available endpoints, request / response formats, and authentication requirements.

Introduction¶

Welcome to the Excalibur v4 API Integration Manual. Excalibur v4 is a powerful Privileged Access Management (PAM) solution designed to secure and streamline privileged account usage. Leveraging custom-built strong Multi-Factor Authentication (MFA), Excalibur v4 enhances security by requiring robust identity verification for access to sensitive resources.

Overview¶

The Excalibur API is part of a comprehensive ecosystem of services within Excalibur, which employs a microservice-based architecture. This API enables integration with Excalibur’s backend services, facilitating secure, seamless interactions with the PAM and MFA components of the system. While the Excalibur v4 API represents one aspect of the broader Excalibur ecosystem, it provides critical endpoints that allow external applications to interface with privileged account management, access control policies, and audit functionalities.

Secure API access is enforced using OAuth 2.0 with client credentials flow for M2M (machine-to-machine) communication, ensuring that only authenticated clients can interact with Excalibur’s resources.

Audience¶

This manual is intended for developers, systems integrators, and security architects who need to integrate Excalibur v4’s PAM and MFA capabilities with their applications or systems. Familiarity with RESTful API conventions, JSON data formatting, and OAuth 2.0 is recommended.

Excalibur’s RESTful API provides an essential interface for seamless integration, enabling you to unlock the full potential of its privileged access and security features within your existing infrastructure.

List of Abbreviations¶

MFA	Multi-Factor Authentication
PAM	Privileged Access Management
API	Application Programming Interface
JSON	JavaScript Object Notation (lightweight data-interchange format)
JWT	JSON Web Token (a compact, URL-safe token format used for securely transmitting information between parties)
M2M	Machine to machine (server to server) communication.

Getting Started¶

This document will guide you through the initial steps to start integrating with the Excalibur v4 API, including setting up API access, configuring your development environment, and making your first authorized request.

REST API¶

The Excalibur v4 API follows a RESTful (Representational State Transfer) architecture, a style for web services that emphasizes a stateless, client-server communication protocol based on HTTP. RESTful APIs use a set of principles that focus on standard HTTP methods and clear, consistent URLs, enabling easy integration and efficient communication between services. By adhering to these principles, RESTful APIs ensure scalability, reliability, and simplicity.

Key REST Principles¶

Statelessness: Each request from a client to the server must contain all the necessary information for the server to fulfill the request. This means that the server does not store session state, making the API scalable and straightforward to manage.
Client-Server Architecture: RESTful APIs use a client-server model, where the client (in this case, applications that connect to Excalibur) and the server (Excalibur API) are separated. This separation allows each component to evolve independently.
Uniform Interface: RESTful APIs use standard URLs and HTTP methods (like GET, POST, PUT, DELETE) for each resource, making the API easier to understand and use.
Cacheability: Responses from the API can be explicitly marked as cacheable or non-cacheable, allowing clients to cache responses to reduce network calls and improve performance.

HTTP Methods and Their Purposes¶

GET: Retrieves data from the server. (Retrieving information about a specific user or a list of users)
POST: Submits new data to the server (Creating a new user, OAuth client, or policy within Excalibur)
PUT: Updates existing data on the server. (Modifying user attributes or permissions)
PATCH: Partially updates an existing resource. Unlike PUT, which requires sending the entire resource with modifications, PATCH allows updating specific fields only. For example (Updating a PAM target name without modifying other attributes).
DELETE: Deletes resources from the server. (Removing a user, tenant, role permissions)

Errors¶

HTTP status codes¶

All of the Excalibur v4 API endpoints could return one of following HTTP status codes in its response to specific request, based on its result

Status code	Reason phrase	Description
200	OK	The request was successful. Typically used for actions that complete as expected and requested data is returned.
201	Created	The request was successful, and a new resource was created. Typically used after a successful POST request (e.g., when a new user is created).
204	No Content	The request was successful, but there is no content to return. Commonly used in PATCH or DELETE operations.
400	Bad Request	The server could not understand the request due to invalid syntax or missing parameters. This error often occurs when required fields are not provided or incorrectly formatted.
401	Unauthorized	The request lacks valid authentication credentials. This can happen if the OAuth token is missing, expired, or incorrect.
403	Forbidden	The client does not have permission to access the requested resource. This typically means the client is authenticated but does not have the necessary permissions.
404	Not Found	The requested resource does not exist. This error can occur when an endpoint is incorrect or a specified resource ID is not found.
409	Conflict	The request failed, because the resource already exists. Typically returned when creating PAM Target with an already used name.
422	Unprocessable Entity	The server could not understand the request due to invalid syntax or missing parameters. This error often occurs when required fields are not provided, incorrectly formatted or outside of allowed range.
500	Internal Server Error	The server encountered an unexpected error. This can be due to various issues on the server-side, such as misconfigurations or system failures.

Application errors¶

Except for common HTTP status, when a request fails, it returns an error code in response body, which better identifies the cause of failure.

Response body example for failed request looks as follows:

{
  "code": 200145
}

For a list of available application error codes see Appendix: Application Error Codes

OAuth 2.0 Authorization¶

The Excalibur v4 API uses the OAuth 2.0 client credentials flow for authentication and authorization of clients. This flow is specifically designed for server-to-server (also known as machine-to-machine) interactions, allowing applications to access resources on behalf of themselves, rather than on behalf of individual users.

Obtaining Client Credentials¶

To access the Excalibur v4 API, client credentials must be generated by an authorized user within the Excalibur application dashboard. Follow these steps to create and manage API credentials

Log in to your Excalibur instance with an account that has sufficient privileges to manage OAuth clients. After successful login, navigate to OAuth client management as seen on the following image and click on the “Add” button to create a new OAuth client.

Fill in required fields for newly created OAuth client¶

On the following screen fill in mandatory fields to create a new OAuth client. OAuth client name, to help you identify OAuth client, validity for issued OAuth client access token. Validity can be entered in human readable format (2 hours, 1 hour 30 minutes, etc.). Last but not least, fill in permissions you want the newly created OAuth client will have. Optionally you can fill in “Description” to help you better understand the purpose of the OAuth client. To submit information provided, click on the “Save” button in the right bottom corner of the page.

Copy and store credentials¶

Upon client creation, copy and securely store client ID and client secret provided. These credentials are essential for authenticating API requests.

Client secret is displayed only once right after it is created and cannot be displayed later!

API Endpoints and Environment Setup¶

Each Excalibur deployment operates on its own Fully Qualified Domain Name (FQDN), and all API endpoints are prefixed with /api/v1. Ensure you are using the correct base URL for your deployment.

(Example Base URL: http(s)://{base_url}/api/v1).

Authenticating Requests with OAuth 2.0 Client Credentials Flow¶

The Excalibur v4 API uses the OAuth 2.0 client credentials flow for authentication and authorization. This flow is specifically suited for server-to-server applications. In order to make API requests, the OAuth client has to request access token first, which will be used in consecutive requests.

Note: Not all API endpoints are authenticated so in order to check availability of your deployment performing GET request to date endpoint (/api/v1/date), which if successful, will return actual server date.

Request Access Token¶

The OAuth token endpoint issues access tokens based on your client credentials (clientID and clientSecret) obtained by following steps described in Obtaining Client Credentials.

In order to obtain access token from Excalibur API you have to send a POST request to the token endpoint (/api/v1/oauth/token) with the following parameters:

Parameter	Description
clientID	Your unique client ID, obtained from the Excalibur application dashboard.
clientSecret	Your unique client secret, obtained from the Excalibur application dashboard.

Example cURL command to request a token:

curl -X POST {base_url}/api/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "clientID": "{YOUR_CLIENT_ID}",
    "clientSecret": "{YOUR_CLIENT_SECRET}"
  }'

Note: Replace {YOUR_CLIENT_ID} and {YOUR_CLIENT_SECRET} with your actual credentials from the Excalibur dashboard.

Explanation:

-X POST: Specifies a POST request.
-H "Content-Type: application/json": Sets the content type required by the OAuth token endpoint.
The data (-d) is passed as a JSON object within single quotes.

Receive Token¶

On success, the OAuth token endpoint will return a JSON response containing the following fields:

Parameter	Description
access_token	JWT token you’ll use for API requests. JWT token is signed with Excalibur server private key.
token_type	The type of token (Bearer).
expires_in	The number of seconds until the token expires.

Example response:

{
  "access_token": "your_access_token",
  "token_type": "Bearer",
  "expires_in": 3600
}

Store the access_token securely, as it will be required for authenticating all API requests made next.

Include Token in Requests¶

Use access_token received in the previous step to authenticate all API requests made by including it in the Authorization header.

The format for this header is Authorization: Bearer {access_token}.

Example cURL command to make an authenticated request:

curl -X GET {base_url}/api/v1/tenants \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json"

Note: Replace {access_token} with access token obtained in previous step.

Explanation:

-X GET: Specifies a GET request to retrieve information.
-H "Authorization: Bearer {access_token}": Adds the access token to the Authorization header.
-H "Content-Type: application/json": Indicates that the request expects a JSON response.

Token expiration¶

The token’s expires_in value specifies its validity period (in seconds). When the access token expires, Excalibur API responds with HTTP status code 401 (Unauthorized) to request being made and you will need to request a new token using your client credentials as described in Request Access Token.

Note: OAuth 2.0 client credentials grant type do not use refresh token as client credentials serves that purpose in case access token is not valid anymore.

This completes the token request and inclusion steps, enabling you to interact securely with Excalibur’s RESTful API.

Webhooks¶

Excalibur v4 offers registering webhooks for long running operations.

Currently only Tenant creation is supported.

Creating webhook¶

Select OAuth client¶

Navigate to OAuth client management as seen on the following image and click on the existing OAuth client.

Add new webhook¶

Click on the “Add” button as seen on the following image to create a new Webhook.

Fill in required fields for newly created Webhook¶

On the following screen fill in mandatory fields to create a new Webhook.

In the “General” section enter the URL which will be called when an event happens and select events you want to subscribe to.

In the “Network” section select if you want to use TLS (Transport layer security) to secure connection to your Webhook endpoint. If enabled, you can either copy or upload Certificate authority (CA) certificate.

In the “Authentication” section select the signature method - either HMAC or Deployment private key. If you choose HMAC you have to enter a secret.

To submit information provided, click on the “Save” button in the right bottom corner of the page.

If you’ve selected Deployment private key as a signature method, you can find and download Deployment public key in settings page:

Editing or deleting webhook¶

To edit or delete webhook use actions in the table showing all webhooks created for the OAuth Client.

Testing webhook¶

In the table showing all webhooks created for the OAuth Client you can see in the “Delivery Status” column if delivery of the last message to the webhook was successful.

If you want to debug the configuration of the webhook you can use the “Send test event” button to send the test event.

Content of webhook messages¶

Common structure¶

Every message is sent with POST request and contains JSON body with following fields:

Field	Description
signature	Signature of data field. Data is signed either with HMAC or Deployment private key based on the webhook configuration.
data	Object containing fields described in following rows.
data.eventType	Name of event type. See subsections Content of tenant creation message and Content of test event message
data.timestamp	Timestamp as a string value in ISO format.
data.payload	Object containing further data. Specific based on event type.

Example message:

{
  "signature": "1b2c16b75bd2a870c114153ccda5bcfca63314bc722fa...",
  "data": {
    "eventType": "EVENT_TYPE",
    "timestamp": "2024-11-14T14:01:20.818Z",
    "payload": {}
  }
}

Content of tenant creation message¶

In addition to common fields, the request contains the following fields:

Field	Description
data.eventType	Constant: 'tenant_creation'
data.payload.tenantID	Tenant ID
data.payload.status	One of these values: 'pending', 'in_progress', 'completed', 'failed', 'decommissioned'

Example message:

{
  "signature": "1b2c16b75bd2a870c114153ccda5bcfca63314bc722fa...",
  "data": {
    "eventType": "tenant_creation",
    "timestamp": "2024-11-14T14:01:20.818Z",
    "payload": {
      "tenantID": 1,
      "status": "in_progress"
    }
  }
}

Content of test event message¶

In addition to common fields, the request contains the following fields:

Field	Description
data.eventType	Constant: 'test'
data.payload	Empty object.

Example message:

{
  "signature": "1b2c16b75bd2a870c114153ccda5bcfca63314bc722fa160d690de133ccbb9db",
  "data": {
    "eventType": "test",
    "timestamp": "2024-11-14T14:01:20.818Z",
    "payload": {}
  }
}

API¶

Detailed auto-generated documentation for all endpoints can be found here.

Query Parameters¶

Excalibur v4 API provides powerful features to customize data retrieval passing request query parameters, including filtering, sorting, column selection, and pagination. Below is an explanation of these features with examples to illustrate their usage.

Filtering¶

Filtering allows clients to refine the results returned by Excalibur v4 API endpoints based on specific conditions. By including filter parameters in the request URL, clients can define criteria for narrowing down data. It supports a variety of operators for precise data filtering.

Filtering Operators¶

The API provides a range of filtering operators to tailor query results based on specific conditions.

Result filtering can be applied to requests by appending filters to request query parameters.

Equality Operator (=)¶

Return users whose name is Adam

/api/v1/users?filter==(name,Adam)

Greater than Operator (>)¶

Return users whose age is greater than 30

/api/v1/users?filter=>(age,30)

Less than Operator (\<)¶

Return users whose age is less than 30

/api/v1/users?filter=<(age,30)

Greater than or equal to Operator (>=)¶

Return users whose age is greater than or equal to 30

/api/v1/users?filter=>=(age,30)

Less than or equal to (\<=)¶

Return users whose age is less than or equal to 30

/api/v1/users?filter=<=(age,30)

Not Equal Operator (\<>)¶

Return users whose name is not Adam

/api/v1/users?filter=<>(name,Adam)

Contains (LIKE) Operator (%)¶

Return users whose name contains “oh” (e.g., "John", "Johnny")

/api/v1/users?filter=%(name,oh)

Starts with Operator (%-)¶

Return users whose name starts with “Joh” (e.g., "John", "Johnny")

/api/v1/users?filter=%-(name,Joh)

End with Operator (-%)¶

Return users whose name ends with “son” (e.g., "Jackson", "Mason")

/api/v1/users?filter=-%(name,son)

Combining Operators¶

Allows to combine multiple filter operators in one request using logical operators

And Operator (and)¶

Combines multiple filters while all combined conditions must be met.

Filter users whose name is John and their age is greater than 30

/api/v1/users?filter=and(=(name,John),>(age,30))

Or Operator (or)¶

Combines multiple filters while at least one condition must be met.

Filter users whose name is John, or their age is less than 30

/api/v1/users?filter=or(=(name,John),<(age,30))

Sorting in the API¶

The API offers robust sorting functionality, enabling clients to control the order in which results are returned. Sorting supports both ascending and descending orders, with advanced options for handling empty or NULL values. Multiple sorting criteria can be applied simultaneously, with higher priority given to the first criterion specified, followed by subsequent ones.

Sorting Features¶

Ascending and Descending Order
- To sort in ascending order, provide the field name directly (e.g., name) or prefix the field with a plus sign + (e.g., +name).
- To sort in descending order, prefix the field with a minus sign - (e.g., -age).
Handling Empty or NULL Values
- Use the ~ prefix to prioritize empty or NULL values over non-empty ones.
- Combine ~ with the + or - prefixes for additional sorting directions.
Multi-Criteria Sorting
- Specify multiple sort criteria, separated by commas (,).
- The first criterion takes precedence, followed by subsequent ones.

Ascending sorting¶

To sort in ascending order, provide the field name directly (e.g., name) or prefix the field with a plus sign + (e.g., +name) in the sort query parameter. By default, when no sorting direction is provided, sorting is in ascending order.

Sort users in ascending order by name before returning result

/api/v1/users?sort=name

Or specify ascending sorting order explicitly

/api/v1/users?sort=+name

Descending sorting¶

To sort in descending order, prefix the field with a minus sign - (e.g., -age) in the sort query parameter.

Sort users in descending order by name before returning result

/api/v1/users?sort=-name

Favor empty values first¶

To favor empty (null) values in the returned result, just prepend tilde ~ before sort sign.

Sort users in descending order with empty values returned first

/api/v1/users?sort=~-name

Multiple sorting¶

Multiple sort conditions can be combined by separating them with “,” comma.

Sort users by age ascending and descending by name, empty names first

/api/v1/users?sort=~-name,age

Column selection¶

Column selection allows clients to specify which fields should be included in the response, optimizing data retrieval by returning only the necessary data.

Columns can be specified by passing them in columns query parameter separated by comma.

By default, all columns are returned if no specific columns are requested.

To return only name, age and email in returned result set

/api/v1/users?columns=name,age,email

Pagination¶

Pagination helps manage large datasets by controlling the number of results and their starting point. This is achieved by passing the limit and offset parameters.

limit: Specify maximum number of results returned (default: 20)
offset: Specify number of records to skip before returning results (default: 0).

To return 10 users starting from 21^st record (skipping the first 20 records)

/api/v1/users?limit=10&offset=20

Combined Usage¶

The API allows combining filtering, sorting, column selection, and pagination in a single request, enabling tailored data retrieval.

To return up to 10 users name, id and email, starting from first user, named John, older than 30 years, sorted by id in descending order and by email in ascending order with empty emails first

/api/v1/users?filter=and(=(name,John),<(createdAt,2024-10-05T14:48:00))&limit=10&offset=0&columns=name,id,email&sort=~email,-id

API endpoints¶

Tenant management¶

Excalibur v4 offers multi-tenant architecture, where tenant refers to a distinct and independent entity (logical instance). Each tenant has its own data, configurations, user permissions, and resources, all managed separately from other tenants. A tenant can represent an organization, a department or a specific user group.

All tenants within one deployment share the underlying infrastructure such as servers, databases, and application code.

Key Characteristics:

Data Isolation: Each tenant's data is separated from others, ensuring privacy and security.
Configuration Independence: Tenants can have unique configurations that tailor the application to their specific needs.
Resource Sharing: While underlying hardware or software resources are shared among tenants, they function as if they have dedicated access.

Create Tenant¶

Endpoint POST /api/v1/tenants
Permissions: tenants_create

This endpoint is designed for creating a new tenant within Excalibur deployment. A tenant in this context is an organizational entity that can have specific configurations, users, identity stores, policies, and access rights.

Despite the fact that Excalibur deployment shares underlying infrastructure, some of the resources in the cluster are created per tenant (services, pods, network policies). Provisioning of those resources takes some time and thus the process of tenant creation is asynchronous. Response is returned immediately after the tenant entity is created within the system and its resources are provisioned afterwards.

Tenant resources are created using a series of asynchronous tasks. Each task may retry if an error occurs, with failures eventually leading to a failed status once retries are exhausted.

Resources typically created as part of the provisioning process in cluster

Headless services
Deployments
Auto-scalers for created deployments
Network Policies

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).
Content-Type: application/json Specifies the format of the request payload.

Path Parameters¶

N/A: This endpoint does not utilize path parameters.

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

name (string): The name of the tenant to create. (Required)
description (string, optional): An optional description of the tenant to help better identify the tenant. (Optional)
slug (string): A unique human readable identifier for the tenant, suitable for use in URLs. (Required) ⚠️This parameter has to be unique within the system and cannot be changed later ⚠️
networkAddresses (array of strings, optional): A list of allowed network address ranges associated with the tenant. (Optional) Those address ranges serve the purpose of whitelisting network addresses which a PAM module of a specific tenant can make connections to. This can be an empty array if no network addresses are specified, thus no validation of PAM target network addresses is done. Meaning all network addresses are allowed. For further details see Network Policy Management.

Example of request body:

{
  "name": "MyTenant",
  "description": "This is a description",
  "slug": "my-tenant",
  "networkAddresses": [
    "192.168.1.4-192.168.1.5"
  ]
}

Response¶

Upon success, application return status code 201 Created and in response body JSON data containing following parameters

id (integer): unique ID of newly created tenant

⚠️Due to asynchronous nature of tenant creation, resource provisioning for created tenant can be in progress at this time. Status of tenant creation can be obtained via pre-configured webhook (see Creating webhook)

Example of response body:

{
  "id": 1234
}

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X POST {base_url}/api/v1/tenants \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MyTenant",
    "description": "This is a description",
    "slug": "my-tenant",
    "networkAddresses": ["192.168.1.4-192.168.1.5"]
  }'

Get Tenant by ID or Slug¶

Endpoint GET /api/v1/tenants/{tenantIdOrSlug}
Permissions: tenants_read

This endpoint retrieves information about a specific tenant by its unique identifier or slug. If the tenant does not exist, a 404 error is returned.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

tenantIdOrSlug (string or integer): The unique identifier or slug of the tenant.

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

N/A: This endpoint does not support request body

Response¶

Upon success, the application returns status code 200 OK and in response body JSON data containing following details:

id (integer): unique ID of the tenant.
name (string): The name of the tenant.
description (string, optional): The description of the tenant.
slug (string): The unique human-readable identifier for the tenant.
networkAddresses (array of strings, optional): The list of allowed network address ranges associated with the tenant.
status (string): The status of the tenant creation process.
errorLog (string, optional): Error message if the tenant creation process failed.
createdAt (string): The date the tenant was created.
updatedAt (string): The date the tenant was last updated.

Example of response body:

{
  "id": 1234,
  "name": "MyTenant",
  "description": "This is a description",
  "slug": "my-tenant",
  "networkAddresses": [
    "192.168.1.4-192.168.1.5"
  ],
  "status": "completed",
  "errorLog": "",
  "createdAt": "2022-01-01T00:00:00.000Z",
  "updatedAt": "2022-01-01T00:00:00.000Z"
}

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

Using tenant slug:

curl -X GET {base_url}/api/v1/tenants/my-tenant \
  -H "Authorization: Bearer {access_token}"

Using tenant ID:

curl -X GET {base_url}/api/v1/tenants/1234 \
  -H "Authorization: Bearer {access_token}"

Get All Tenants¶

Endpoint GET /api/v1/tenants
Permissions: tenants_read

This endpoint retrieves a paginated collection of tenants with optional filtering, sorting, and column selection.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

N/A: This endpoint does not utilize path parameters.

Query Parameters¶

This endpoint supports filtering, pagination and sorting as described in Excalibur v4 API Query Parameters section.

Request Body¶

N/A: This endpoint does not support request body

Response¶

Upon success, the application returns status code 200 OK and in response body JSON data containing the paginated list of tenants containing total number of tenants and array of returned tenants.

total (integer): The total number of tenants.
entities (array): The list of tenants, each containing:
- id (integer, optional): unique ID of the tenant.
- name (string, optional): The name of the tenant.
- description (string, optional): The description of the tenant.
- slug (string, optional): The unique human-readable identifier for the tenant.
- networkAddresses (array of strings, optional): The list of allowed network address ranges associated with the tenant.
- status (string, optional): The status of the tenant creation process.
- createdAt (string, optional): The date the tenant was created.
- updatedAt (string, optional): The date the tenant was last updated.

Example of response body:

{
  "total": 2,
  "entities": [
    {
      "id": 1234,
      "name": "MyTenant",
      "description": "This is a description",
      "slug": "my-tenant",
      "networkAddresses": [
        "192.168.1.4-192.168.1.5"
      ],
      "status": "completed",
      "createdAt": "2022-01-01T00:00:00.000Z",
      "updatedAt": "2022-01-01T00:00:00.000Z"
    },
    {
      "id": 5678,
      "name": "AnotherTenant",
      "description": "This is another description",
      "slug": "another-tenant",
      "networkAddresses": [
        "192.168.2.4-192.168.2.5"
      ],
      "status": "completed",
      "createdAt": "2022-01-01T00:00:00.000Z",
      "updatedAt": "2022-01-01T00:00:00.000Z"
    }
  ]
}

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

Retrieve the first page with a limit of 5 tenants:

curl -X GET {base_url}/api/v1/tenants?offset=0&limit=5 \
  -H "Authorization: Bearer {access_token}"

Retrieve tenants sorted by name:

curl -X GET {base_url}/api/v1/tenants?sort=name \
  -H "Authorization: Bearer {access_token}"

Update Tenant¶

Endpoint PATCH /api/v1/tenants/{tenantId}
Permissions: tenants_update

This endpoint allows for updating the details of an existing tenant by its ID or slug. Only the fields provided in the request body will be updated, allowing for partial updates.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).
Content-Type: application/json Specifies the format of the request payload.

Path Parameters¶

tenantId (string): The unique identifier or slug of the tenant to update.

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

name (string, optional): The new name of the tenant.
description (string, optional): The new description of the tenant.
networkAddresses (array of strings, optional): The new list of allowed network address ranges associated with the tenant.

Example of request body:

{
  "name": "UpdatedTenant",
  "description": "This is an updated description",
  "networkAddresses": [
    "192.168.1.6-192.168.1.7"
  ]
}

Response¶

Upon success, the application returns status code 204 No Content, indicating that the tenant was successfully updated.

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X PATCH {base_url}/api/v1/tenants/1234 \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "UpdatedTenant",
    "description": "This is an updated description",
    "networkAddresses": ["192.168.1.6-192.168.1.7"]
  }'

Delete Tenant¶

Endpoint DELETE /api/v1/tenants/{tenantId}
Permissions: tenants_delete

This endpoint allows for deleting an existing tenant by its ID. Once deleted, the tenant's data and resources are permanently removed and cannot be recovered.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

tenantId (string): The unique identifier or slug of the tenant to delete.

Query Parameters¶

forceDelete (boolean): A boolean flag symbolizing if the tenant should be deleted immediately (if true) or decommissioned first and deleted later (if false [default])
scheduledPermanentDeleteAt (string): A date in ISO 8601 format representing when the tenant should be scheduled for deletion. Required when forceDelete is false.

Request Body¶

N/A: This endpoint does not support request body

Response¶

Upon success, the application returns status code 204 No Content, indicating that the tenant was successfully deleted.

In case an error happens during processing the request, the API will respond with one of the error codes described in Common HTTP Status Codes and Errors.

Example¶

curl -X DELETE {base_url}/api/v1/tenants/1234?scheduledPermanentDeleteAt=2029-12-31T12:00:00.000Z \
  -H "Authorization: Bearer {access_token}"

Delete Multiple Tenants¶

Endpoint DELETE /api/v1/tenants
Permissions: tenants_delete

This endpoint allows for deleting multiple tenants by their unique identifiers. It expects an array of tenant IDs to be provided via the query parameter. If no IDs are provided, a 422 Unprocessable Entity error is returned.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

N/A: This endpoint does not utilize path parameters.

Query Parameters¶

ids (array of integers): The unique identifiers of the tenants to delete.
forceDelete (boolean): A boolean flag symbolizing if the tenant should be deleted immediately (if true) or decommissioned first and deleted later (if false [default])
scheduledPermanentDeleteAt (string): A date in ISO 8601 format representing when the tenant should be scheduled for deletion. Required when forceDelete is false.

Request Body¶

N/A: This endpoint does not support request body

Response¶

Upon success, the application returns status code 204 No Content indicating that the tenants were successfully deleted.

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X DELETE {base_url}/api/v1/tenants?ids[]=1234&ids[]=5678&scheduledPermanentDeleteAt=2029-12-31T12:00:00.000Z \
  -H "Authorization: Bearer {access_token}"

Get tenant’s recordings expiration time¶

Endpoint GET /api/v1/pam/recording-expires-at
Permissions: tenants_read

This endpoint retrieves the time when the last recording in a given tenant expires. This time can be used for decommissioning tenants.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

N/A: This endpoint does not utilize path parameters.

Query Parameters¶

tenantIDs (array of integers): The unique identifiers of the tenants to check.

Request Body¶

N/A: This endpoint does not support request body

Response¶

Upon success, the application returns status code 200 OK and in response body JSON data containing the list of tenants each with its own expiration time.

results (array): The list of tenants, each containing:
- tenantID (integer): unique ID of the tenant.
- maxExpiresAt (string, optional): The date in a ISO 8601 format representing the maximum expiration time in this tenant.

Example of response body:

{
  "results": [
    {
      "tenantID": 1
    },
    {
      "tenantID": 1,
      "maxExpiresAt": "2022-01-01T00:00:00.000Z"
    }
  ]
}

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

Retrieve the expiration time for a single tenant:

curl -X GET {base_url}/api/v1/pam/recording-expires-at?tenantIDs=1 \
  -H "Authorization: Bearer {access_token}"

Retrieve the expiration time for a multiple tenants:

curl -X GET {base_url}/api/v1/pam/recording-expires-at?tenantIDs=1&?tenantIDs=2 \
  -H "Authorization: Bearer {access_token}"

Network Policy Management¶

Network policies create network policy resources in the cluster which allow outgoing connections from tenant-dedicated PAM pods only to specified IP addresses or subnets, ensuring users can't make connections elsewhere. Network policies are created with tenants (see Create Tenant) and can be updated or deleted by changing the network addresses using the PUT method.

Example Network Policies¶

Below are some example network policies that illustrate how different network address ranges can be configured to control outgoing connections from tenant-dedicated PAM pods. These policies ensure that connections are only allowed to specified addresses, enhancing security and compliance.

Network policy is a list of addresses, where each address is in one of the following format

192.168.1.4 Allows connections to a specific IP
192.168.1.0/24 Allows connections to a specific subnet defined in CIDR format
2001:db8::/32 Allows connections to an IPv6 range
92.168.1.4-192.168.1.5 Allows connections to an IP range
example.com Allows connections to a specific hostname

Note

When hostname is used as an address in network policy address list, it is resolved to IPs and set in the network policy afterward. When in time the host DNS record gets changed, it does not affect existing network policy and previously resolved IPs are still applied.

When updating network policy, Excalibur always validates input data format to ensure input addresses are valid.

Get Network Policies¶

Endpoint GET /api/v1/networkPolicies
Permissions: network_policies_read

This endpoint retrieves a collection of system network policies.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

N/A: This endpoint does not utilize path parameters.

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

N/A: This endpoint does not support request body

Response¶

Upon success, the application returns status code 200 OK and in response body JSON data containing the total number of returned entries, while each of entry contains following parameters

total (integer): The total number of network policies.
entities (array): A list of network policy objects.
- id (integer): The unique identifier of the network policy.
- tenantID (integer, optional): The unique identifier of the tenant, or null if not applicable.
- networkAddress (string): The network address associated with the policy.

Example of response body:

{
  "total": 2,
  "entities": [
    {
      "id": 4321,
      "tenantID": null,
      "networkAddress": "127.1.2.9"
    },
    {
      "id": 4322,
      "tenantID": null,
      "networkAddress": "127.1.1.10"
    }
  ]
}

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X GET {base_url}/api/v1/networkPolicies \
  -H "Authorization: Bearer {access_token}"

Update Network Policy¶

Endpoint PUT /api/v1/networkPolicies
Permissions: network_policies_update

This endpoint allows for updating the details of the existing network policy. The entire list of network addresses must be provided in the request body, as partial updates are not supported.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).
Content-Type: application/json Specifies the format of the request payload.

Path Parameters¶

N/A: This endpoint does not utilize path parameters.

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

networkAddresses (array of strings): The complete list of allowed network address ranges associated with the tenant.

Example of request body:

{
  "networkAddresses": [
    "192.168.1.6",
    "192.168.1.0/24",
    "2001:db8::/32",
    "192.168.1.6-192.168.1.7"
  ]
}

Response¶

Upon success, the application returns status code 204 No Content indicating that the network policy was successfully updated.

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X PUT {base_url}/api/v1/networkPolicies \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "networkAddresses": ["192.168.1.6", "192.168.1.0/24", "2001:db8::/32", "192.168.1.6-192.168.1.7"]
  }'

Delete Network Policy¶

Endpoint PUT /api/v1/networkPolicies
Permissions: network_policies_update

This endpoint also allows deletion of the existing network policy by providing an empty array in the request body. This reuses the same endpoint as updating the policy to simplify the API design.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

N/A: This endpoint does not utilize path parameters.

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

networkAddresses (array of strings): Provide an empty array to delete the network policy.

Example of request body to delete the network policy:

{
  "networkAddresses": []
}

Response¶

Upon success, the application returns status code 204 No Content indicating that the network policy was successfully deleted.

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X PUT {base_url}/api/v1/networkPolicies \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "networkAddresses": []
  }'

Get Network Policies for Tenant¶

Endpoint GET /api/v1/tenants/{tenantIdOrSlug}/networkPolicies
Permissions: network_policies_read

This endpoint retrieves the network policies for a specific tenant.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

tenantIdOrSlug (string or integer): The unique identifier or slug of the tenant.

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

N/A: This endpoint does not support request body

Response¶

Upon success, the application returns status code 200 OK and in response body JSON data containing the list of network policies with their total count. Each network policy contains following parameters

total (integer): The total number of network policies for the tenant.
entities (array): A list of network policy objects.
- id (integer): The unique identifier of the network policy.
- tenantID (integer): The unique identifier of the tenant.
- networkAddress (string): The network address associated with the policy.

Example of response body:

{
  "total": 2,
  "entities": [
    {
      "id": 4321,
      "tenantID": 1234,
      "networkAddress": "127.1.2.9"
    },
    {
      "id": 4322,
      "tenantID": 1234,
      "networkAddress": "127.1.1.10"
    }
  ]
}

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X GET {base_url}/api/v1/tenants/1234/networkPolicies \
  -H "Authorization: Bearer {access_token}"

Update Network Policy for Tenant¶

Endpoint PUT /api/v1/tenants/{tenantIdOrSlug}/networkPolicies
Permissions: network_policies_update

This endpoint allows for updating the network policy for a specific tenant. The entire list of network addresses must be provided in the request body, as partial updates are not supported.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).
Content-Type: application/json Specifies the format of the request payload.

Path Parameters¶

tenantIdOrSlug (string or integer): The unique identifier or slug of the tenant.

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

networkAddresses (array of strings): The complete list of allowed network address ranges associated with the tenant.

Example of request body:

{
  "networkAddresses": [
    "192.168.1.6",
    "192.168.1.0/24",
    "2001:db8::/32",
    "192.168.1.6-192.168.1.7"
  ]
}

Response¶

Upon success, the application returns status code 204 No Content indicating that the network policy for the tenant was successfully updated.

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X PUT {base_url}/tenants/1234/networkPolicies \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "networkAddresses": ["192.168.1.6", "192.168.1.0/24", "2001:db8::/32", "192.168.1.6-192.168.1.7"]
  }'

Delete Network Policy for Tenant¶

Endpoint PUT /api/v1/tenants/{tenantIdOrSlug}/networkPolicies
Permissions: network_policies_update

This endpoint also allows for deleting the network policy for a specific tenant by providing an empty array in the request body. This reuses the same endpoint as updating the policy to simplify the API design.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

tenantIdOrSlug (string or integer): The unique identifier or slug of the tenant.

Request Body

networkAddresses (array of strings): Provide an empty array to delete the network policy.

Example of request body to delete the network policy:

{
  "networkAddresses": []
}

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

N/A: This endpoint does not support request body

Response¶

Upon success, the application returns status code 204 No Content indicating that the network policy for the tenant was successfully deleted.

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X PUT {base_url}/tenants/1234/networkPolicies \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "networkAddresses": []
  }'

Identity Stores Management¶

Identity stores are external directories, such as LDAP servers, that store user and group information. They are used to invite, register, authenticate and authorize users within the Excalibur system. By integrating with identity stores, Excalibur can leverage existing user management infrastructure, ensuring consistency and security across the organization.

Key Characteristics:

Centralized User Management: Identity stores allow for centralized management of user credentials and permissions.
Scalability: They support large numbers of users and groups, making them suitable for enterprise environments.
Security: By using established protocols and encryption methods, identity stores ensure secure authentication and authorization processes.
Ecosystem Integration: Identity stores are a crucial part of the Excalibur ecosystem. They must be configured to invite users to Excalibur. Every time a user is registered, authenticated, or authorized, the identity store is used to ensure the account is not expired, disabled, etc.

Create AD Identity Store¶

Endpoint POST /api/v1/identityStores
Permissions: identity_stores_create

This endpoint facilitates the creation of a new identity store by connecting to an LDAP server, specifically Active Directory in Excalibur deployment system scope. Upon successful connection, the identity store details are saved in the database, and its users are synchronized with the Excalibur system.

Users are synchronized with identity stores periodically just for improved searching performance when searching for users to invite.

If the connection fails due to invalid credentials or other issues, an error is returned, and the identity store is not created.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).
Content-Type: application/json Specifies the format of the request payload.

Path Parameters¶

N/A: This endpoint does not utilize path parameters.

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

name (string): The name of the identity store.
description (string, optional): An optional description of the identity store.
baseDN (string): The base distinguished name (DN) for the LDAP directory.
configurations (array): Defines the connection settings for the identity store.
- tunnelID (integer, optional): The tunnelID of the tunnel used for the identity store connection.
- active (boolean): A boolean indicating whether the identity store configuration is active.
- bindDN (string): The distinguished name (DN) to bind to the LDAP server.
- host (string): The host address of the LDAP server.
- port (integer): The port number of the LDAP server.
- password (string): The password for the bind DN.
- useTLS (boolean): Whether to use TLS for the connection.
- caCertificate (string, optional): The CA certificate for TLS connection. Only used when useTLS is set to true.

Example of request body:

{
  "name": "MyIdentityStore",
  "description": "This is a description",
  "baseDN": "dc=example,dc=com",
  "configurations": [
    {
      "tunnelID": null,
      "active": true,
      "host": "ldap.example.com",
      "port": 636,
      "bindDN": "cn=admin,dc=example,dc=com",
      "password": "password",
      "useTLS": true,
      "caCertificate": "-----BEGIN CERTIFICATE-----\n..."
    }
  ]
}

Response¶

Upon success, the application returns status code 201 Created and in response body JSON data containing the following parameters:

(integer): unique ID of the newly created identity store

Example of response body:

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X POST {base_url}/api/v1/identityStores \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MyIdentityStore",     "description": "This is a description",
    "baseDN": "dc=example,dc=com",
    "configurations: [{       "tunnelID": null,       "active": true,
      "host": "ldap.example.com",
      "port": 636,
      "bindDN": "cn=admin,dc=example,dc=com",
      "password": "password",
      "useTLS": true
    }]
  }'

Create AD Identity Store in Tenant¶

Endpoint POST /api/v1/tenants/{tenantIdOrSlug}/identityStores
Permissions: identity_stores_create

This endpoint facilitates the creation of a new identity store within a specified tenant of Excalibur deployment. The rest of its behavior is the same as in Create AD Identity Store

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).
Content-Type: application/json Specifies the format of the request payload.

Path Parameters¶

tenantIdOrSlug (string or integer): The unique identifier or slug of the tenant.

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

name (string): The name of the identity store.
description (string, optional): An optional description of the identity store.
baseDN (string): The base distinguished name (DN) for the LDAP directory.
configurations (array): Defines the connection settings for the identity store.
- tunnelID (integer, optional): The tunnelID of the tunnel used for the identity store connection.
- active (boolean): A boolean indicating whether the identity store configuration is active.
- bindDN (string): The distinguished name (DN) to bind to the LDAP server.
- host (string): The host address of the LDAP server.
- port (integer): The port number of the LDAP server.
- password (string): The password for the bind DN.
- useTLS (boolean): Whether to use TLS for the connection.
- caCertificate (string, optional): The CA certificate for TLS connection. Only used when useTLS is set to true.

Example of request body:

{
  "name": "MyIdentityStore",
  "description": "This is a description",
  "baseDN": "dc=example,dc=com",
  "configurations": [
    {
      "tunnelID": null,
      "active": true,
      "host": "ldap.example.com",
      "port": 389,
      "bindDN": "cn=admin,dc=example,dc=com",
      "password": "password",
      "useTLS": false
    }
  ]
}

Response¶

Upon success, the application returns status code 201 Created and in response body JSON data containing the following parameters:

(integer): unique ID of the newly created identity store

Example of response body:

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X POST {base_url}/api/v1/tenants/{tenantIdOrSlug}/identityStores \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MyIdentityStore",     "description": "This is a description",
    "baseDN": "dc=example,dc=com",
    "configurations: [{       "tunnelID": null,       "active": true,
      "host": "ldap.example.com",
      "port": 389,
      "bindDN": "cn=admin,dc=example,dc=com",
      "password": "password",
      "useTLS": false
    }]
  }'

Create Entra Identity Store¶

Endpoint POST /api/v1/identityStores/entra
Permissions: identity_stores_create

This endpoint facilitates the creation of a new identity store by connecting to an Microsoft Entra Identity Provider. Upon successful connection, the identity store details are saved in the database, and its users are synchronized with the Excalibur system.

If the connection fails due to invalid credentials or other issues, an error is returned, and the identity store is not created.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).
Content-Type: application/json Specifies the format of the request payload.

Path Parameters¶

N/A: This endpoint does not utilize path parameters.

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

name (string): The name of the identity store.
description (string, optional): An optional description of the identity store.
clientID (string): Microsoft Entra application (client) ID.
clientSecret (string): Microsoft Entra application (client) secret.
entraTenantID (string): Microsoft Entra tenant ID.

Example of request body:

{
  "name": "MyIdentityStore",
  "description": "This is a description",
  "clientID": "7f0d64d0-08e5-486a-ba63-0d98d5c5a356",
  "clientSecret": "secret123",
  "entraTenantID": "f48ec115-83f7-4ec3-94cd-f00917f92f22"
}

Response¶

Upon success, the application returns status code 201 Created and in response body JSON data containing the following parameters:

(integer): unique ID of the newly created identity store

Example of response body:

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X POST {base_url}/api/v1/identityStores \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '
    {
      "name": "MyIdentityStore",
      "description": "This is a description",
      "clientID": "7f0d64d0-08e5-486a-ba63-0d98d5c5a356",
      "clientSecret": "secret123",
      "entraTenantID": "f48ec115-83f7-4ec3-94cd-f00917f92f22"
    }
  '

Create Entra Identity Store in Tenant¶

Endpoint POST /api/v1/tenants/{tenantIdOrSlug}/identityStores/entra
Permissions: identity_stores_create

This endpoint facilitates the creation of a new Entra identity store within a specified tenant of Excalibur deployment. The rest of its behavior is the same as in Create Entra Identity Store

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).
Content-Type: application/json Specifies the format of the request payload.

Path Parameters¶

tenantIdOrSlug (string or integer): The unique identifier or slug of the tenant.

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

name (string): The name of the identity store.
description (string, optional): An optional description of the identity store.
clientID (string): Microsoft Entra application (client) ID.
clientSecret (string): Microsoft Entra application (client) secret.
entraTenantID (string): Microsoft Entra tenant ID.

Example of request body:

{
  "name": "MyIdentityStore",
  "description": "This is a description",
  "clientID": "7f0d64d0-08e5-486a-ba63-0d98d5c5a356",
  "clientSecret": "secret123",
  "entraTenantID": "7f0d64d0-08e5-486a-ba63-0d98d5c5a356"
}

Response¶

Upon success, the application returns status code 201 Created and in response body JSON data containing the following parameters:

(integer): unique ID of the newly created identity store

Example of response body:

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X POST {base_url}/api/v1/tenants/{tenantIdOrSlug}/identityStores \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '
    {
      "name": "MyIdentityStore",
      "description": "This is a description",
      "clientID": "7f0d64d0-08e5-486a-ba63-0d98d5c5a356",
      "clientSecret": "secret123",
      "entraTenantID": "f48ec115-83f7-4ec3-94cd-f00917f92f22"
    }
  '

Create Excalibur Local Identity Store¶

Endpoint POST /api/v1/identityStores/local
Permissions: identity_stores_create

This endpoint facilitates the creation of a new local identity store, which is internal to your Excalibur deployment.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).
Content-Type: application/json Specifies the format of the request payload.

Path Parameters¶

N/A: This endpoint does not utilize path parameters.

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

name (string): The name of the identity store.
description (string, optional): An optional description of the identity store.

Example of request body:

{
  "name": "MyIdentityStore",
  "description": "This is a description"
}

Response¶

Upon success, the application returns status code 201 Created and in response body JSON data containing the following parameters:

(integer): unique ID of the newly created identity store

Example of response body:

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X POST {base_url}/api/v1/identityStores \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '
    {
      "name": "MyIdentityStore",
      "description": "This is a description"
    }
  '

Create Excalibur Local Identity Store in Tenant¶

Endpoint POST /api/v1/tenants/{tenantIdOrSlug}/identityStores/local
Permissions: identity_stores_create

This endpoint facilitates the creation of a new local identity store, which is internal to your Excalibur deployment. The rest of its behavior is the same as in Create Excalibur Local Identity Store

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).
Content-Type: application/json Specifies the format of the request payload.

Path Parameters¶

tenantIdOrSlug (string or integer): The unique identifier or slug of the tenant.

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

name (string): The name of the identity store.
description (string, optional): An optional description of the identity store.

Example of request body:

{
  "name": "MyIdentityStore",
  "description": "This is a description"
}

Response¶

Upon success, the application returns status code 201 Created and in response body JSON data containing the following parameters:

(integer): unique ID of the newly created identity store

Example of response body:

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X POST {base_url}/api/v1/tenants/{tenantIdOrSlug}/identityStores \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '
    {
      "name": "MyIdentityStore",
      "description": "This is a description"
    }
  '

Get Identity Store by ID¶

Endpoint GET /api/v1/identityStores/{id}
Permissions: identity_stores_read

This endpoint retrieves detailed information about a specific identity store by its unique identifier. If the identity store does not exist, a 404 error is returned.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

id (string): The unique identifier of the identity store.

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

N/A: This endpoint does not support request body

Response¶

Upon success, the application returns status code 200 OK and in response body JSON data containing the identity store details.

id (string): The unique identifier of the identity store.
name (string): The name of the identity store.
tenantId (integer, optional): The identifier of the tenant that owns the identity store.
description (string, optional): A description of the identity store.
type (enum): The type of the identity store. Can be one of "ldap", "entra" or "excalibur".
additionalProperties (object, optional): Extra properties which depend on each individual Identity Store type.
- baseDN (string): The base distinguished name (DN) for the LDAP directory.
- configurations: (array):
  - id (string): The unique identifier of the identity store configuration.
  - host (string): The host address of the LDAP server.
  - port (integer): The port number of the LDAP server.
  - bindDN (string): The distinguished name (DN) to bind to the LDAP server.
  - useTLS (boolean): Whether TLS is used for the connection.
  - caCertificate (string, optional): The CA certificate for TLS connection. Only used when useTLS is set to true.
  - priority (number): Defines the execution order of active identity store configurations. When multiple configurations have "active": true, the one with the lowest priority value is used first.
  - active (boolean): A boolean indicating whether the identity store configuration is active.
  - lastConnected (string): The lastConnected is Timestamp of the most recent successful connection to the LDAP server, represented in ISO 8601 format.
  - isConnected: (boolean): Indicates whether the identity store is currently connected to the LDAP server.
  - tunnelID (integer, optional): The tunnelID of the tunnel used for the identity store connection.
  - tunnelName (string, optional): The tunnelName of the tunnel used for the identity store connection.

Example of response body:

{
  "id": 1,
  "name": "MyIdentityStore",
  "description": "This is a description",
  "tenantId": 0,
  "type": "ldap",
  "additionalProperties": {
    "baseDN": "dc=example,dc=com",
    "configurations": [
      {
        "id": 1,
        "priority": 1,
        "tunnelName": null,
        "tunnelID": null,
        "isConnected": true,
        "lastConnected": "2024-10-25T17:54:32.937Z",
        "active": true,
        "host": "ldap.example.com",
        "port": 636,
        "bindDN": "cn=admin,dc=example,dc=com",
        "password": "password",
        "useTLS": true,
        "caCertificate": "-----BEGIN CERTIFICATE-----\n..."
      }
    ]
  }
}

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X GET {base_url}/api/v1/identityStores/1234 \
  -H "Authorization: Bearer {access_token}"

Get Tenant Identity Store by ID¶

Endpoint GET /api/v1/tenants/{tenantIdOrSlug}/identityStores/{id}
Permissions: identity_stores_read

This endpoint retrieves detailed information about a specific identity store within a specified tenant by its unique identifier. If the identity store does not exist, a 404 error is returned.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

tenantIdOrSlug (string or integer): The unique identifier or slug of the tenant.
id (string): The unique identifier of the identity store.

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

N/A: This endpoint does not support request body

Response¶

Upon success, the application returns status code 200 OK and in response body JSON data containing the identity store details.

id (string): The unique identifier of the identity store.
name (string): The name of the identity store.
tenantId (integer, optional): The identifier of the tenant that owns the identity store.
description (string, optional): A description of the identity store.
type (enum): The type of the identity store. Can be one of "ldap", "entra" or "excalibur".
additionalProperties (object, optional): Extra properties which depend on each individual Identity Store type.
- baseDN (string): The base distinguished name (DN) for the LDAP directory.
- configurations: (array): The list of configurations of identity stores.
  - id (string): The unique identifier of the identity store configuration.
  - host (string): The host address of the LDAP server.
  - port (integer): The port number of the LDAP server.
  - bindDN (string): The distinguished name (DN) to bind to the LDAP server.
  - useTLS (boolean): Whether TLS is used for the connection.
  - caCertificate (string, optional): The CA certificate for TLS connection. Only used when useTLS is set to true.
  - priority (number): Defines the execution order of active identity store configurations. When multiple configurations have "active": true, the one with the lowest priority value is used first.
  - active (boolean): A boolean indicating whether the identity store configuration is active.
  - lastConnected (string): The lastConnected is Timestamp of the most recent successful connection to the LDAP server, represented in ISO 8601 format.
  - isConnected: (boolean): Indicates whether the identity store is currently connected to the LDAP server.
  - tunnelID (integer, optional): The tunnelID of the tunnel used for the identity store connection.
  - tunnelName (string, optional): The tunnelName of the tunnel used for the identity store connection.

Example of response body:

{
  "id": 1,
  "name": "MyIdentityStore",
  "description": "This is a description",
  "tenantId": 0,
  "type": "ldap",
  "additionalProperties": {
    "baseDN": "dc=example,dc=com",
    "configurations": [
      {
        "id": 1,
        "priority": 1,
        "tunnelName": null,
        "tunnelID": null,
        "isConnected": true,
        "lastConnected": "2024-10-25T17:54:32.937Z",
        "active": true,
        "host": "ldap.example.com",
        "port": 389,
        "bindDN": "cn=admin,dc=example,dc=com",
        "password": "password",
        "useTLS": true,
        "caCertificate": "-----BEGIN CERTIFICATE-----\n..."
      }
    ]
  }
}

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

Using tenant slug:

curl -X GET {base_url}/api/v1/tenants/my-tenant/identityStores/1234 \
  -H "Authorization: Bearer {access_token}"

Using tenant ID:

curl -X GET {base_url}/api/v1/tenants/1234/identityStores/1234 \
  -H "Authorization: Bearer {access_token}"

Get Identity Store collection¶

Endpoint GET /api/v1/identityStores
Permissions: identity_stores_read

This endpoint retrieves a collection of identity stores with optional sorting and pagination.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

N/A: This endpoint does not utilize path parameters.

Query Parameters¶

This endpoint supports filtering, pagination and sorting as described in Excalibur v4 API Query Parameters section.

Request Body¶

N/A: This endpoint does not support request body

Response¶

Upon success, the application returns status code 200 OK and in response body JSON data containing the paginated list of identity stores.

total (integer): The total number of identity stores.
entities (array): The list of identity stores.
- id (string): The unique identifier of the identity store.
- name (string): The name of the identity store.
- tenantId (integer, optional): The identifier of the tenant that owns the identity store.
- description (string, optional): A description of the identity store.
- type (enum): The type of the identity store. Can be one of "ldap", "entra" or "excalibur".
- additionalProperties (object, optional): Extra properties which depend on each individual Identity Store type.
  - baseDN (string): The base distinguished name (DN) for the LDAP directory. (only for type "ldap")
  - configurations: (array): The list of configurations of identity stores. (only for type "ldap")
    - id (string): The unique identifier of the identity store configuration.
    - host (string): The host address of the LDAP server.
    - port (integer): The port number of the LDAP server.
    - bindDN (string): The distinguished name (DN) to bind to the LDAP server.
    - useTLS (boolean): Whether TLS is used for the connection.
    - caCertificate (string, optional): The CA certificate for TLS connection. Only used when useTLS is set to true.
    - priority (number): Defines the execution order of active identity store configurations. When multiple configurations have "active": true, the one with the lowest priority value is used first.
    - active (boolean): A boolean indicating whether the identity store configuration is active.
    - lastConnected (string): The lastConnected is Timestamp of the most recent successful connection to the LDAP server, represented in ISO 8601 format.
    - isConnected: (boolean): Indicates whether the identity store is currently connected to the LDAP server.
    - tunnelID (integer, optional): The tunnelID of the tunnel used for the identity store connection.
    - tunnelName (string, optional): The tunnelName of the tunnel used for the identity store connection.
  - clientID (string): Microsoft Entra application (client) ID. (only for type "entra")
  - entraTenantID (string): Microsoft Entra tenant ID. (only for type "entra")

Example of response body:

{
  "total": 2,
  "entities": [
    {
      "id": 1,
      "name": "MyIdentityStore",
      "description": "This is a description",
      "tenantId": 0,
      "type": "ldap",
      "additionalProperties": {
        "baseDN": "dc=example,dc=com",
        "configurations": [
          {
            "id": 1,
            "priority": 1,
            "tunnelName": null,
            "tunnelID": null,
            "isConnected": true,
            "lastConnected": "2024-10-25T17:54:32.937Z",
            "active": true,
            "host": "ldap.example.com",
            "port": 636,
            "bindDN": "cn=admin,dc=example,dc=com",
            "password": "password",
            "useTLS": true,
            "caCertificate": "-----BEGIN CERTIFICATE-----\n..."
          }
        ]
      }
    },
    {
      "id": 2,
      "name": "MyIdentityStore2",
      "description": "This is a description",
      "tenantId": 0,
      "type": "ldap",
      "additionalProperties": {
        "baseDN": "dc=example,dc=com",
        "configurations": [
          {
            "id": 1,
            "priority": 1,
            "tunnelName": null,
            "tunnelID": null,
            "isConnected": true,
            "lastConnected": "2024-10-25T17:54:32.937Z",
            "active": true,
            "host": "ldap.example.com",
            "port": 636,
            "bindDN": "cn=admin,dc=example,dc=com",
            "password": "password",
            "useTLS": false
          }
        ]
      }
    },
    {
      "id": 3,
      "name": "MyIdentityStore3",
      "description": "This is a description",
      "tenantId": 0,
      "type": "entra",
      "additionalProperties": {
        "clientID": "7f0d64d0-08e5-486a-ba63-0d98d5c5a356",
        "entraTenantID": "f48ec115-83f7-4ec3-94cd-f00917f92f22"
      }
    },
    {
      "id": 4,
      "name": "MyIdentityStore4",
      "description": "This is a description",
      "tenantId": 0,
      "type": "excalibur"
    }
  ]
}

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

Retrieve the first page with a limit of 5 identity stores:

curl -X GET {base_url}/api/v1/identityStores?offset=0&limit=5 \
  -H "Authorization: Bearer {access_token}"

Retrieve identity stores sorted by name:

curl -X GET {base_url}/api/v1/identityStores?sort=name \
  -H "Authorization: Bearer {access_token}"

Get Tenant Identity Store collection¶

Endpoint GET /api/v1/tenants/{tenantIdOrSlug}/identityStores
Permissions: identity_stores_read

This endpoint retrieves a collection of identity stores within a specified tenant with optional sorting and pagination.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

tenantIdOrSlug (string or integer): The unique identifier or slug of the tenant.

Query Parameters¶

This endpoint supports filtering, pagination and sorting as described in Excalibur v4 API Query Parameters section.

Request Body¶

N/A: This endpoint does not support request body

Response¶

Upon success, the application returns status code 200 OK and in response body JSON data containing the paginated list of identity stores.

total (integer): The total number of identity stores.
entities (array): The list of identity stores.
- id (string): The unique identifier of the identity store.
- name (string): The name of the identity store.
- tenantId (integer, optional): The identifier of the tenant that owns the identity store.
- description (string, optional): A description of the identity store.
- type (enum): The type of the identity store. Can be one of "ldap", "entra" or "excalibur".
- additionalProperties (object, optional): Extra properties which depend on each individual Identity Store type.
  - baseDN (string): The base distinguished name (DN) for the LDAP directory. (only for type "ldap")
  - configurations: (array): The list of configurations of identity stores. (only for type "ldap")
    - id (string): The unique identifier of the identity store configuration.
    - host (string): The host address of the LDAP server.
    - port (integer): The port number of the LDAP server.
    - bindDN (string): The distinguished name (DN) to bind to the LDAP server.
    - useTLS (boolean): Whether TLS is used for the connection.
    - caCertificate (string, optional): The CA certificate for TLS connection. Only used when useTLS is set to true.
    - priority (number): Defines the execution order of active identity store configurations. When multiple configurations have "active": true, the one with the lowest priority value is used first.
    - active (boolean): A boolean indicating whether the identity store configuration is active.
    - lastConnected (string): The lastConnected is Timestamp of the most recent successful connection to the LDAP server, represented in ISO 8601 format.
    - isConnected: (boolean): Indicates whether the identity store is currently connected to the LDAP server.
    - tunnelID (integer, optional): The tunnelID of the tunnel used for the identity store connection.
    - tunnelName (string, optional): The tunnelName of the tunnel used for the identity store connection.
  - clientID (string): Microsoft Entra application (client) ID. (only for type "entra")
  - entraTenantID (string): Microsoft Entra tenant ID. (only for type "entra")

Example of response body:

{
  "total": 2,
  "entities": [
    {
      "id": 1,
      "name": "MyIdentityStore",
      "description": "This is a description",
      "tenantId": 0,
      "type": "ldap",
      "additionalProperties": {
        "baseDN": "dc=example,dc=com",
        "configurations": [
          {
            "id": 1,
            "priority": 1,
            "tunnelName": null,
            "tunnelID": null,
            "isConnected": true,
            "lastConnected": "2024-10-25T17:54:32.937Z",
            "active": true,
            "host": "ldap.example.com",
            "port": 636,
            "bindDN": "cn=admin,dc=example,dc=com",
            "password": "password",
            "useTLS": true,
            "caCertificate": "-----BEGIN CERTIFICATE-----\n..."
          }
        ]
      }
    },
    {
      "id": 2,
      "name": "MyIdentityStore2",
      "description": "This is a description",
      "tenantId": 0,
      "type": "ldap",
      "additionalProperties": {
        "baseDN": "dc=example,dc=com",
        "configurations": [
          {
            "id": 1,
            "priority": 1,
            "tunnelName": null,
            "tunnelID": null,
            "isConnected": true,
            "lastConnected": "2024-10-25T17:54:32.937Z",
            "active": true,
            "host": "ldap.example.com",
            "port": 636,
            "bindDN": "cn=admin,dc=example,dc=com",
            "password": "password",
            "useTLS": false
          }
        ]
      }
    },
    {
      "id": 3,
      "name": "MyIdentityStore3",
      "description": "This is a description",
      "tenantId": 0,
      "type": "entra",
      "additionalProperties": {
        "clientID": "7f0d64d0-08e5-486a-ba63-0d98d5c5a356",
        "entraTenantID": "f48ec115-83f7-4ec3-94cd-f00917f92f22"
      }
    },
    {
      "id": 4,
      "name": "MyIdentityStore4",
      "description": "This is a description",
      "tenantId": 0,
      "type": "excalibur"
    }
  ]
}

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

Retrieve the first page with a limit of 5 identity stores:

curl -X GET {base_url}/api/v1/tenants/{tenantIdOrSlug}/identityStores?offset=0&limit=5 \
  -H "Authorization: Bearer {access_token}"

Retrieve identity stores sorted by name:

curl -X GET {base_url}/api/v1/tenants/{tenantIdOrSlug}/identityStores?sort=name \
  -H "Authorization: Bearer {access_token}"

Verify AD Identity Store¶

Endpoint POST /api/v1/identityStores/verify-connection
Permissions: identity_stores_update

This endpoint verifies the connection to an LDAP server (e.g., Active Directory) within the Excalibur deployment system scope.

If the connection is successful, the API returns confirmation that the LDAP server can be reached.
If the connection fails (invalid credentials, wrong host, etc.), an error response is returned, and no identity store is created.

User synchronization with identity stores occurs periodically to improve performance when searching for users to invite.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).
Content-Type: application/json Specifies the format of the request payload.

Path Parameters¶

N/A: This endpoint does not utilize path parameters.

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

name (string): The name of the identity store.
description (string, optional): An optional description of the identity store.
baseDN (string): The base distinguished name (DN) for the LDAP directory.
configurations (array): Defines the connection settings for the identity store.
- tunnelID (integer): The tunnelID of the tunnel used for the identity store connection.
- active (boolean): A boolean indicating whether the identity store configuration is active.
- bindDN (string): The distinguished name (DN) to bind to the LDAP server.
- host (string): The host address of the LDAP server.
- port (integer): The port number of the LDAP server.
- password (string): The password for the bind DN.
- useTLS (boolean): Whether to use TLS for the connection.
- caCertificate (string, optional): The CA certificate for TLS connection. Only used when useTLS is set to true.

Example of request body:

{
  "name": "MyIdentityStore",
  "description": "This is a description",
  "baseDN": "dc=example,dc=com",
  "configurations": [
    {
      "tunnelID": null,
      "active": true,
      "host": "ldap.example.com",
      "port": 636,
      "bindDN": "cn=admin,dc=example,dc=com",
      "password": "password",
      "useTLS": true,
      "caCertificate": "-----BEGIN CERTIFICATE-----\n..."
    }
  ]
}

Response¶

Success (200 OK)

The request returns a JSON object indicating whether the connection to the LDAP server was successful.

canConnect (boolean): true if the LDAP connection can be established, otherwise false.

Example Success Response body :

{
  "canConnect": true
}

Example Failure Response body :

{
  "canConnect": false
}

Update AD Identity Store¶

Endpoint PATCH /api/v1/identityStores/{id}
Permissions: identity_stores_update

This endpoint allows for updating the details of an existing LDAP identity store by its ID. Only the fields provided in the request body will be updated, allowing for partial updates. If the specified identity store is not found, a 404 error is returned.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).
Content-Type: application/json Specifies the format of the request payload.

Path Parameters¶

id (string): The unique identifier of the identity store to update.

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

name (string, optional): The name of the identity store.
description (string, optional): An optional description of the identity store.
baseDN (string, optional): The base distinguished name (DN) for the LDAP directory.
configurations: (array): The list of configurations of identity stores.
- id (string): The unique identifier of the identity store configuration.
- tunnelID (integer, optional): The tunnelID of the tunnel used for the identity store connection.
- active (boolean, optional): A boolean indicating whether the identity store configuration is active.
- bindDN (string, optional): The distinguished name (DN) to bind to the LDAP server.
- host (string, optional): The host address of the LDAP server.
- port (integer, optional): The port number of the LDAP server.
- password (string, optional): The password for the bind DN.
- useTLS (boolean, optional): Whether to use TLS for the connection.
- caCertificate (string, optional): The CA certificate for TLS connection. Only used when useTLS is set to true.

Example of request body:

{
  "name": "UpdatedIdentityStore",
  "baseDN": "dc=updated,dc=com",
  "description": "This is an updated description",
  "configurations": [
    {
      "id": 1,
      "priority": 1,
      "tunnelID": null,
      "active": true,
      "host": "ldap.example.com",
      "port": 636,
      "bindDN": "cn=admin,dc=example,dc=com",
      "password": "password",
      "useTLS": true,
      "caCertificate": "-----BEGIN CERTIFICATE-----\n..."
    }
  ]
}

Response¶

Upon success, the application returns status code 204 No Content, indicating that the identity store was successfully updated.

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X {base_url}/api/v1/identityStores/1234 \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '
    {
      "name": "UpdatedIdentityStore",
      "baseDN": "dc=updated,dc=com",
      "description": "This is an updated description",
      "configurations": [
        {
          "id": 1,
          "priority": 1,
          "tunnelID": null,
          "active": true,
          "host": "ldap.example.com",
          "port": 636,
          "bindDN": "cn=admin,dc=example,dc=com",
          "password": "password",
          "useTLS": true,
          "caCertificate": "-----BEGIN CERTIFICATE-----\n..."
        }
      ]
    }
  '

Update AD Identity Store in Tenant¶

Endpoint: PATCH /api/v1/tenants/{tenantIdOrSlug}/identityStores/{id}
Permissions: identity_stores_update

This endpoint allows for updating the details of an existing LDAP identity store within a specified tenant by its ID. Only the fields provided in the request body will be updated, allowing for partial updates. If the specified identity store is not found, a 404 error is returned.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).
Content-Type: application/json Specifies the format of the request payload.

Path Parameters¶

tenantIdOrSlug (string or integer): The unique identifier or slug of the tenant.
id (string): The unique identifier of the identity store to update.

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

id (integer): The unique identifier of the identity store.
name (string): The name of the identity store.
tenantId (integer, optional): The identifier of the tenant that owns the identity store. If not provided, the identity store is created without tenant association.
description (string): An optional description of the identity store.
baseDN (string): The base distinguished name (DN) for the LDAP directory.
configurations: (array): The list of configurations of identity stores.
- id (string): The unique identifier of the identity store configuration.
- tunnelID (integer, optional): The tunnelID of the tunnel used for the identity store connection.
- active (boolean, optional): A boolean indicating whether the identity store configuration is active.
- bindDN (string, optional): The distinguished name (DN) to bind to the LDAP server.
- host (string, optional): The host address of the LDAP server.
- port (integer, optional): The port number of the LDAP server.
- password (string, optional): The password for the bind DN.
- useTLS (boolean, optional): Whether to use TLS for the connection.
- caCertificate (string, optional): The CA certificate for TLS connection. Only used when useTLS is set to true.

Example of request body:

{
  "name": "UpdatedIdentityStore",
  "baseDN": "dc=updated,dc=com",
  "description": "This is an updated description",
  "configurations": [
    {
      "id": 1,
      "priority": 1,
      "tunnelID": null,
      "active": true,
      "host": "ldap.example.com",
      "port": 636,
      "bindDN": "cn=admin,dc=example,dc=com",
      "password": "password",
      "useTLS": true,
      "caCertificate": "-----BEGIN CERTIFICATE-----\n..."
    }
  ]
}

Response¶

Upon success, the application returns status code 204 No Content, indicating that the identity store was successfully updated.

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X PATCH {base_url}/api/v1/tenants/{tenantIdOrSlug}/identityStores/1234 \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '
    {
      "name": "UpdatedIdentityStore",
      "baseDN": "dc=updated,dc=com",
      "description": "This is an updated description",
      "configurations": [
        {
          "id": 1,
          "priority": 1,
          "tunnelID": null,
          "active": true,
          "host": "ldap.example.com",
          "port": 636,
          "bindDN": "cn=admin,dc=example,dc=com",
          "password": "password",
          "useTLS": true,
          "caCertificate": "-----BEGIN CERTIFICATE-----\n..."
        }
      ]
    }
  '

Update Entra Identity Store¶

Endpoint PATCH /api/v1/identityStores/entra/{id}
Permissions: identity_stores_update

This endpoint allows for updating the details of an existing Entra identity store by its ID. Only the fields provided in the request body will be updated, allowing for partial updates. If the specified identity store is not found, a 404 error is returned.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).
Content-Type: application/json Specifies the format of the request payload.

Path Parameters¶

id (string): The unique identifier of the identity store to update.

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

name (string, optional): The name of the identity store.
description (string, optional): An optional description of the identity store.
clientID (string, optional): Microsoft Entra application (client) ID.
clientSecret (string, optional): Microsoft Entra application (client) secret.
entraTenantID (string, optional): Microsoft Entra tenant ID.

Example of request body:

{
  "name": "MyIdentityStore",
  "description": "This is a description",
  "clientID": "7f0d64d0-08e5-486a-ba63-0d98d5c5a356",
  "clientSecret": "secret123",
  "entraTenantID": "7f0d64d0-08e5-486a-ba63-0d98d5c5a356"
}

Response¶

Upon success, the application returns status code 204 No Content, indicating that the identity store was successfully updated.

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X {base_url}/api/v1/identityStores/1234 \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '
    {
      "name": "MyIdentityStore",
      "description": "This is a description",
      "clientID": "7f0d64d0-08e5-486a-ba63-0d98d5c5a356",
      "clientSecret": "secret123",
      "entraTenantID": "7f0d64d0-08e5-486a-ba63-0d98d5c5a356"
    }
  '

Update Entra Identity Store in Tenant¶

Endpoint: PATCH /api/v1/tenants/{tenantIdOrSlug}/identityStores/entra/{id}
Permissions: identity_stores_update

This endpoint allows for updating the details of an existing Entra identity store within a specified tenant by its ID. Only the fields provided in the request body will be updated, allowing for partial updates. If the specified identity store is not found, a 404 error is returned.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).
Content-Type: application/json Specifies the format of the request payload.

Path Parameters¶

tenantIdOrSlug (string or integer): The unique identifier or slug of the tenant.
id (string): The unique identifier of the identity store to update.

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

name (string, optional): The name of the identity store.
description (string, optional): An optional description of the identity store.
clientID (string, optional): Microsoft Entra application (client) ID.
clientSecret (string, optional): Microsoft Entra application (client) secret.
entraTenantID (string, optional): Microsoft Entra tenant ID.

Example of request body:

{
  "name": "MyIdentityStore",
  "description": "This is a description",
  "clientID": "7f0d64d0-08e5-486a-ba63-0d98d5c5a356",
  "clientSecret": "secret123",
  "entraTenantID": "7f0d64d0-08e5-486a-ba63-0d98d5c5a356"
}

Response¶

Upon success, the application returns status code 204 No Content, indicating that the identity store was successfully updated.

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X {base_url}/api/v1/identityStores/1234 \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '
    {
      "name": "MyIdentityStore",
      "description": "This is a description",
      "clientID": "7f0d64d0-08e5-486a-ba63-0d98d5c5a356",
      "clientSecret": "secret123",
      "entraTenantID": "7f0d64d0-08e5-486a-ba63-0d98d5c5a356"
    }
  '

Update Excalibur Local Identity Store¶

Endpoint PATCH /api/v1/identityStores/local/{id}
Permissions: identity_stores_update

This endpoint allows for updating the details of an existing Excalibur local identity store by its ID. Only the fields provided in the request body will be updated, allowing for partial updates. If the specified identity store is not found, a 404 error is returned.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).
Content-Type: application/json Specifies the format of the request payload.

Path Parameters¶

id (string): The unique identifier of the identity store to update.

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

name (string, optional): The name of the identity store.
description (string, optional): An optional description of the identity store.

Example of request body:

{
  "name": "MyIdentityStore",
  "description": "This is a description"
}

Response¶

Upon success, the application returns status code 204 No Content, indicating that the identity store was successfully updated.

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X {base_url}/api/v1/identityStores/1234 \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '
    {
      "name": "MyIdentityStore",
      "description": "This is a description"
    }
  '

Update Excalibur Local Identity Store in Tenant¶

Endpoint: PATCH /api/v1/tenants/{tenantIdOrSlug}/identityStores/local/{id}
Permissions: identity_stores_update

This endpoint allows for updating the details of an existing Excalibur local identity store within a specified tenant by its ID. Only the fields provided in the request body will be updated, allowing for partial updates. If the specified identity store is not found, a 404 error is returned.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).
Content-Type: application/json Specifies the format of the request payload.

Path Parameters¶

tenantIdOrSlug (string or integer): The unique identifier or slug of the tenant.
id (string): The unique identifier of the identity store to update.

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

name (string, optional): The name of the identity store.
description (string, optional): An optional description of the identity store.

Example of request body:

{
  "name": "MyIdentityStore",
  "description": "This is a description"
}

Response¶

Upon success, the application returns status code 204 No Content, indicating that the identity store was successfully updated.

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X {base_url}/api/v1/identityStores/1234 \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '
    {
      "name": "MyIdentityStore",
      "description": "This is a description"
    }
  '

Delete Identity Store¶

Endpoint DELETE /api/v1/identityStores/{id}
Permissions: identity_stores_delete

This endpoint allows for deleting an existing identity store by its ID of any type. Once deleted, the identity store's data and resources are permanently removed and cannot be recovered. Users managed by this identity store will not be able to use Excalibur anymore.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

id (string): The unique identifier of the identity store to update.

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

N/A: This endpoint does not support request body

Response¶

Upon success, the application returns status code 204 No Content, indicating that the identity store was successfully deleted.

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X DELETE {base_url}/api/v1/identityStores/1234 \
  -H "Authorization: Bearer {access_token}"

Delete Identity Store from Tenant¶

Endpoint DELETE /api/v1/tenants/{tenantIdOrSlug}/identityStores/{id}
Permissions: identity_stores_delete

This endpoint allows for deleting an existing identity store of any type within a specified tenant by its ID. Once deleted, the identity store's data and resources are permanently removed and cannot be recovered.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

tenantIdOrSlug (string or integer): The unique identifier or slug of the tenant.
id (string): The unique identifier of the identity store to delete.

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

N/A: This endpoint does not support request body

Response¶

Upon success, the application returns status code 204 No Content, indicating that the identity store was successfully deleted.

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X DELETE {base_url}/api/v1/tenants/{tenantIdOrSlug}/identityStores/1234 \
  -H "Authorization: Bearer {access_token}"

Delete Multiple Identity Stores¶

Endpoint DELETE /api/v1/identityStores
Permissions: identity_stores_delete

This endpoint allows for deleting multiple identity stores of any type by their unique identifiers. It expects an array of identity store IDs to be provided via the query parameter. If no IDs are provided, a 422 Unprocessable Entity error is returned.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

N/A: This endpoint does not utilize path parameters.

Query Parameters¶

ids (array of integers): The unique identifiers of the identity stores to delete.

Request Body¶

N/A: This endpoint does not support request body

Response¶

Upon success, the application returns status code 204 No Content indicating that the identity stores were successfully deleted.

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X DELETE {base_url}/api/v1/identityStores?ids[]=1234&ids[]=5678 \
  -H "Authorization: Bearer {access_token}"

Delete Multiple Identity Stores from Tenant¶

Endpoint DELETE /api/v1/tenants/{tenantIdOrSlug}/identityStores
Permissions: identity_stores_delete

This endpoint allows for deleting multiple identity stores of any type within a specified tenant by their unique identifiers. It expects an array of identity store IDs to be provided via the query parameter. If no IDs are provided, a 422 Unprocessable Entity error is returned.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

tenantIdOrSlug (string or integer): The unique identifier or slug of the tenant.

Query Parameters¶

ids (array of integers): The unique identifiers of the identity stores to delete.

Request Body¶

N/A: This endpoint does not support request body

Response¶

Upon success, the application returns status code 204 No Content indicating that the identity stores were successfully deleted.

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X DELETE {base_url}/api/v1/tenants/{tenantIdOrSlug}/identityStores?ids[]=1234&ids[]=5678 \
  -H "Authorization: Bearer {access_token}"

Get Users from Identity Store¶

Endpoint GET /api/v1/identityStores/{id}/users
Permissions: identity_stores_read and users_read_all

This endpoint retrieves a list of users associated with a specific identity store identified by its ID. The response includes pagination support through limit and offset parameters, allowing clients to control the number of returned users and the starting point for retrieval. Additionally, filtering, sorting, and specific column selection can be applied to customize the response.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

id (string): The unique identifier of the identity store.

Query Parameters¶

This endpoint supports filtering, pagination and sorting as described in Excalibur v4 API Query Parameters section.

Request Body¶

N/A: This endpoint does not support request body

Response¶

Upon success, the application returns status code 200 OK and in response body JSON data containing the list of users.

total (integer): The total number of users.
entities (array): The list of user objects.
- userID (integer or null): The ID of the user within the system, to which the invitation is related.
- uuid (string): The unique identifier of the user.
- email (string): The email address of the user.
- username (string): The username of the user.
- name (string): The first name of the user.
- surname (string): The last name of the user.

Example of response body:

{
  "total": 2,
  "entities": [
    {
      "userID": 1,
      "uuid": "asdasdewd",
      "email": "user@email.com",
      "username": "JohnDoe",
      "name": "John",
      "surname": "Doe"
    },
    {
      "userID": 2,
      "uuid": "asdasdewd",
      "email": "user2@email.com",
      "username": "JaneDoe",
      "name": "Jane",
      "surname": "Doe"
    }
  ]
}

| |

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X GET {base_url}/api/v1/identityStores/1234/users \
  -H "Authorization: Bearer {access_token}"

Get Users from Tenant Identity Store¶

Endpoint GET /api/v1/tenants/{tenantIdOrSlug}/identityStores/{id}/users
Permissions: identity_stores_read and users_read_all

This endpoint retrieves a list of users associated with a specific identity store within a specified tenant, identified by its ID. The response includes pagination support through limit and offset parameters, allowing clients to control the number of returned users and the starting point for retrieval. Additionally, filtering, sorting, and specific column selection can be applied to customize the response.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

tenantIdOrSlug (string or integer): The unique identifier or slug of the tenant.
id (string): The unique identifier of the identity store.

Query Parameters¶

This endpoint supports filtering, pagination and sorting as described in Excalibur v4 API Query Parameters section.

Request Body¶

N/A: This endpoint does not support request body

Response¶

Upon success, the application returns status code 200 OK and in response body JSON data containing the list of users.

total (integer): The total number of users.
entities (array): The list of user objects.
- userID (integer or null): The ID of the user within the system, to which the invitation is related.
- uuid (string): The unique identifier of the user.
- email (string): The email address of the user.
- username (string): The username of the user.
- name (string): The first name of the user.
- surname (string): The last name of the user.

Example of response body:

{
  "total": 2,
  "entities": [
    {
      "userID": 1,
      "uuid": "asdasdewd",
      "email": "user@email.com",
      "username": "JohnDoe",
      "name": "John",
      "surname": "Doe"
    },
    {
      "userID": 2,
      "uuid": "asdasdewd",
      "email": "user2@email.com",
      "username": "JaneDoe",
      "name": "Jane",
      "surname": "Doe"
    }
  ]
}

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

Using tenant slug:

curl -X GET {base_url}/api/v1/tenants/my-tenant/identityStores/1234/users \
  -H "Authorization: Bearer {access_token}"

Using tenant ID:

curl -X GET {base_url}/api/v1/tenants/123/identityStores/1234/users \
  -H "Authorization: Bearer {access_token}"

Add Users to Excalibur Local Identity Store¶

Endpoint POST /api/v1/identityStores/local/{id}/users
Permissions: identity_stores_update

This endpoint adds a list of users to a specific Excalibur local identity store identified by its ID.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

id (string): The unique identifier of the identity store.

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

users (array of objects):
- name (string): the first name of the user.
- surname (string, optional): the last name of the user.
- email (string, optional): user’s email address.

Example of request body:

{
  "users": [
    {
      "name": "John",
      "surname": "Smith",
      "email": "john.smith@test.com"
    },
    {
      "name": "Amanda",
      "surname": "Smith",
      "email": "amanda.smith@test.com"
    }
  ]
}

Response¶

Upon success, the application returns status code 201 Created and in response body JSON data containing the following parameters:

(array of strings): array of UUIDs, one for each added user

Example of response body:

[
  "076e0e50-302d-491e-8e49-3361b26d9bde",
  "5c88bb59-e2da-49e9-8581-06dd9e51d547"
]

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X GET {base_url}/api/v1/identityStores/local/1234/users \
  -H "Authorization: Bearer {access_token}"
  -H "Content-Type: application/json" \
  -d '
    {
      "users": [
        {
          "name": "John",
          "surname": "Smith",
          "email": "john.smith@test.com"
        },
        {
          "name": "Amanda",
          "surname": "Smith",
          "email": "amanda.smith@test.com"
        }
      ]
    }
  '

Add Users to Tenant Excalibur Local Identity Store¶

Endpoint POST /api/v1/tenants/{tenantIdOrSlug}/identityStores/local/{id}/users
Permissions: identity_stores_update

This endpoint adds a list of users to a specific Excalibur local identity store identified by its ID in a specific tenant.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

tenantIdOrSlug (string or number): The unique identifier or slug of the tenant.
id (integer): The unique identifier of the identity store.

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

users (array of objects):
- name (string): the first name of the user.
- surname (string, optional): the last name of the user.
- email (string, optional): user’s email address.

Example of request body:

{
  "users": [
    {
      "name": "John",
      "surname": "Smith",
      "email": "john.smith@test.com"
    },
    {
      "name": "Amanda",
      "surname": "Smith",
      "email": "amanda.smith@test.com"
    }
  ]
}

Response¶

Upon success, the application returns status code 201 Created and in response body JSON data containing the following parameters:

(array of strings): array of UUIDs, one for each added user

Example of response body:

[
  "076e0e50-302d-491e-8e49-3361b26d9bde",
  "5c88bb59-e2da-49e9-8581-06dd9e51d547"
]

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

Using tenant slug:

curl -X POST {base_url}/api/v1/tenants/my-tenant/identityStores/local/1234/users \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '
    {
      "users": [
        {
          "name": "John",
          "surname": "Smith",
          "email": "john.smith@test.com"
        },
        {
          "name": "Amanda",
          "surname": "Smith",
          "email": "amanda.smith@test.com"
        }
      ]
    }
  '

Using tenant ID:

curl -X POST {base_url}/api/v1/tenants/123/identityStores/local/1234/users \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '
    {
      "users": [
        {
          "name": "John",
          "surname": "Smith",
          "email": "john.smith@test.com"
        },
        {
          "name": "Amanda",
          "surname": "Smith",
          "email": "amanda.smith@test.com"
        }
      ]
    }
  '

Delete Users from Excalibur Local Identity Store¶

Endpoint DELETE /api/v1/identityStores/local/{id}/users
Permissions: identity_stores_update

This endpoint removes a list of users from a specific Excalibur local identity store identified by its ID.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

id (string): The unique identifier of the identity store.

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

ids (array of integers): An array of user IDs to delete.

Example of request body:

{
  "ids": [
    123,
    456
  ]
}

Response¶

Upon success, the application returns status code 204 No Content with no response body.

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X GET {base_url}/api/v1/identityStores/local/1234/users \
  -H "Authorization: Bearer {access_token}"
  -H "Content-Type: application/json" \
  -d '
    {
      "ids": [
        123,
        456
      ]
    }
  '

Delete Users from Tenant Excalibur Local Identity Store¶

Endpoint DELETE /api/v1/tenants/{tenantIdOrSlug}/identityStores/local/{id}/users
Permissions: identity_stores_update

This endpoint removes a list of users from a specific Excalibur local identity store identified by its ID in a specific tenant.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

tenantIdOrSlug (string or number): The unique identifier or slug of the tenant.
id (integer): The unique identifier of the identity store.

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

ids (array of integers): An array of user IDs to delete.

Example of request body:

{
  "ids": [
    123,
    456
  ]
}

Response¶

Upon success, the application returns status code 204 No Content with no response body.

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

Using tenant slug:

curl -X POST {base_url}/api/v1/tenants/my-tenant/identityStores/local/1234/users \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '
    {
      "ids": [
        123,
        456
      ]
    }
  '

Using tenant ID:

curl -X POST {base_url}/api/v1/tenants/123/identityStores/local/1234/users \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '
    {
      "ids": [
        123,
        456
      ]
    }
  '

Update Users in Excalibur Local Identity Store¶

Endpoint PATCH /api/v1/identityStores/local/{id}/users
Permissions: identity_stores_update

This endpoint updates a list of users in a specific Excalibur local identity store identified by its ID.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

id (string): The unique identifier of the identity store.

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

users (array of objects):
- id (integer): user’s unique ID. Should match the ID of the user you are updating.
- uuid (string): user’s unique UUID. Should match the UUID of the user you are updating.
- name (string, optional): the first name of the user.
- surname (string, optional): the last name of the user.
- username (string, optional): the username of the user.
- email (string, optional): user’s email address.

Example of request body:

{
  "users": [
    {
      "id": 123,
      "uuid": "076e0e50-302d-491e-8e49-3361b26d9bde",
      "name": "John",
      "surname": "Smith",
      "email": "john.smith@test.com"
    },
    {
      "id": 456,
      "uuid": "5c88bb59-e2da-49e9-8581-06dd9e51d547",
      "name": "Amanda",
      "surname": "Smith",
      "email": "amanda.smith@test.com"
    }
  ]
}

Response¶

Upon success, the application returns status code 204 No Content with no response body.

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X GET {base_url}/api/v1/identityStores/local/1234/users \
  -H "Authorization: Bearer {access_token}"
  -H "Content-Type: application/json" \
  -d '
    {
      "ids": [
        123,
        456
      ]
    }
  '

Update Users in Tenant Excalibur Local Identity Store¶

Endpoint PATCH /api/v1/tenants/{tenantIdOrSlug}/identityStores/local/{id}/users
Permissions: identity_stores_update

This endpoint updates a list of users in a specific Excalibur local identity store identified by its ID in a specific tenant.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

tenantIdOrSlug (string or number): The unique identifier or slug of the tenant.
id (integer): The unique identifier of the identity store.

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

users (array of objects):
- id (integer): user’s unique ID. Should match the ID of the user you are updating.
- uuid (string): user’s unique UUID. Should match the UUID of the user you are updating.
- name (string, optional): the first name of the user.
- surname (string, optional): the last name of the user.
- username (string, optional): the username of the user.
- email (string, optional): user’s email address.

Example of request body:

{
  "users": [
    {
      "id": 123,
      "uuid": "076e0e50-302d-491e-8e49-3361b26d9bde",
      "name": "John",
      "surname": "Smith",
      "email": "john.smith@test.com"
    },
    {
      "id": 456,
      "uuid": "5c88bb59-e2da-49e9-8581-06dd9e51d547",
      "name": "Amanda",
      "surname": "Smith",
      "email": "amanda.smith@test.com"
    }
  ]
}

Response¶

Upon success, the application returns status code 204 No Content with no response body.

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

Using tenant slug:

curl -X POST {base_url}/api/v1/tenants/my-tenant/identityStores/local/1234/users \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '
    {
      "users": [
        {
          "id": 123,
          "uuid": "076e0e50-302d-491e-8e49-3361b26d9bde",
          "name": "John",
          "surname": "Smith",
          "email": "john.smith@test.com"
        },
        {
          "id": 456,
          "uuid": "5c88bb59-e2da-49e9-8581-06dd9e51d547",
          "name": "Amanda",
          "surname": "Smith",
          "email": "amanda.smith@test.com"
        }
      ]
    }
  '

Using tenant ID:

curl -X POST {base_url}/api/v1/tenants/123/identityStores/local/1234/users \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '
    {
      "users": [
        {
          "id": 123,
          "uuid": "076e0e50-302d-491e-8e49-3361b26d9bde",
          "name": "John",
          "surname": "Smith",
          "email": "john.smith@test.com"
        },
        {
          "id": 456,
          "uuid": "5c88bb59-e2da-49e9-8581-06dd9e51d547",
          "name": "Amanda",
          "surname": "Smith",
          "email": "amanda.smith@test.com"
        }
      ]
    }
  '

Users Management¶

The Users and User Groups API provides endpoints for viewing users in the Excalibur system.

Get User Groups¶

Endpoint GET /api/v1/userGroups
Permissions: user_groups_read

This endpoint retrieves the list of user groups in the Excalibur system.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

N/A: This endpoint does not support request body

Query Parameters¶

This endpoint supports filtering, pagination and sorting as described in Excalibur v4 API Query Parameters section.

Request Body¶

N/A: This endpoint does not support request body

Response¶

Upon success, the application returns status code 200 OK and in response body JSON data containing the details of the user groups. The response body will contain the following fields:

total (integer): The total number of invitations.
entities (array): A list of invitations, each with the following parameters:
- id (number): User group’s unique ID.
- name (string): The name of the user group.
- description (string, optional): The description of the user group.
- isBuiltIn (boolean): Indicates whether this group is one of the builtin user groups (one of: Administrators, Auditors, Users) or a custom group created later.
- totalUsers (number): The number of users associated with this user group.
- updatedAt (string): The date and time when the user group was last updated.
- createdAt (string): The date and time when the user group was created.

Example of response body:

{
  "total": 3,
  "entities": [
    {
      "id": 4,
      "isBuiltIn": false,
      "name": "Custom",
      "description": "Custom users group",
      "totalUsers": 5,
      "createdAt": "2025-01-01T00:00:00Z",
      "updatedAt": "2025-01-01T00:00:00Z"
    },
    {
      "id": 3,
      "isBuiltIn": true,
      "name": "Users",
      "description": "System users group",
      "totalUsers": 10,
      "createdAt": "2025-01-01T00:00:00Z",
      "updatedAt": "2025-01-01T00:00:00Z"
    },
    {
      "id": 2,
      "isBuiltIn": true,
      "name": "Auditors",
      "description": "System auditors group",
      "totalUsers": 1,
      "createdAt": "2025-01-01T00:00:00Z",
      "updatedAt": "2025-01-01T00:00:00Z"
    },
    {
      "id": 1,
      "isBuiltIn": true,
      "name": "Administrators",
      "description": "System administrators group",
      "totalUsers": 1,
      "createdAt": "2025-01-01T00:00:00Z",
      "updatedAt": "2025-01-01T00:00:00Z"
    }
  ]
}

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X GET {base_url}/api/v1/userGroups \
  -H "Authorization: Bearer {access_token}"

Get User Groups in Tenant¶

Endpoint GET /api/v1/tenants/{tenantIdOrSlug}/userGroups
Permissions: user_groups_read

This endpoint retrieves the list of user groups in the Excalibur system in a specific tenant.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

N/A: This endpoint does not support request body

Query Parameters¶

This endpoint supports filtering, pagination and sorting as described in Excalibur v4 API Query Parameters section.

Request Body¶

N/A: This endpoint does not support request body

Response¶

Upon success, the application returns status code 200 OK and in response body JSON data containing the details of the user groups. The response body will contain the following fields:

total (integer): The total number of invitations.
entities (array): A list of invitations, each with the following parameters:
- id (number): User group’s unique ID.
- name (string): The name of the user group.
- description (string, optional): The description of the user group.
- isBuiltIn (boolean): Indicates whether this group is one of the builtin user groups (one of: Administrators, Auditors, Users) or a custom group created later.
- totalUsers (number): The number of users associated with this user group.
- updatedAt (string): The date and time when the user group was last updated.
- createdAt (string): The date and time when the user group was created.

Example of response body:

{
  "total": 3,
  "entities": [
    {
      "id": 1004,
      "isBuiltIn": false,
      "name": "Custom",
      "description": "Custom users group",
      "totalUsers": 5,
      "createdAt": "2025-01-01T00:00:00Z",
      "updatedAt": "2025-01-01T00:00:00Z"
    },
    {
      "id": 1003,
      "isBuiltIn": true,
      "name": "Users",
      "description": "System users group",
      "totalUsers": 10,
      "createdAt": "2025-01-01T00:00:00Z",
      "updatedAt": "2025-01-01T00:00:00Z"
    },
    {
      "id": 1002,
      "isBuiltIn": true,
      "name": "Auditors",
      "description": "System auditors group",
      "totalUsers": 1,
      "createdAt": "2025-01-01T00:00:00Z",
      "updatedAt": "2025-01-01T00:00:00Z"
    },
    {
      "id": 1001,
      "isBuiltIn": true,
      "name": "Administrators",
      "description": "System administrators group",
      "totalUsers": 1,
      "createdAt": "2025-01-01T00:00:00Z",
      "updatedAt": "2025-01-01T00:00:00Z"
    }
  ]
}

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X GET {base_url}/api/v1/tenants/1/userGroups \
  -H "Authorization: Bearer {access_token}"

User Invitations Management¶

The User Invitations API provides endpoints for inviting users to the Excalibur system. The invitations can be created for multiple users simultaneously. The invited users will receive an email with a secure invitation link, which they can use to register and join the system.

In order to invite user into Excalibur, identity store must be added first (see Create AD Identity Store)

E-mail address where email with a secure invitation link is sent is obtained from a pre-configured identity store. In the case of Active Directory it is the user object mail attribute by default, or attribute which is configured as an e-mail address in Excalibur (for example userPrincipalName)

In case the user does not have the mail attribute set in the identity store, no email is sent and invitation link has to be copied from Excalibur dashboard by Administrator after successful login, from list of invitations in invitations view.

Invitation Statuses¶

Invitation in Excalibur can be in one of the following states:

pending: The invitation is pending and has not been accepted or declined yet.
sent: The invitation has been successfully sent to the user.
failed: The invitation failed to be sent to the user.
dismissed: The invitation has been dismissed by a user with sufficient privileges.
accepted: The invitation has been accepted by the user.
blocked: The invitation has been blocked by providing an invalid credential when accepting the invitation.
expired: The invitation is no longer valid because its expiration date has passed.

Invite Users¶

Endpoint POST /api/v1/users/invitations
Permissions: users_invitations_create

This endpoint facilitates the invitation of users to the Excalibur system. By providing the necessary user details in the request body, multiple users can be invited simultaneously. Upon successful invitation, users will receive an email with a secure invitation link with instructions how to register and join the system.

If the same user is invited again, the status of their previous invitation will be updated to 'disabled'.

Right after the invitation is created, the status of the invitation will be 'pending'. The invitation will by default expire in 24 hours (can be configured in the system settings). The invited users will be assigned to the default 'Users' user group, unless specified otherwise.

An invitation entity will be created for each invited user immediately after the request is processed. Sending of the invitation emails will be handled asynchronously by the system. Results of the invitation process can be checked by querying the invitation entity.

Note: User account with appropriate user ID must be already present in the identity store and must have an email address configured.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).
Content-Type: application/json Specifies the format of the request payload.

Path Parameters¶

N/A: This endpoint does not utilize path parameters.

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

uuids (array of strings): The UUIDs of the users to be invited. In case the identity store is Active Directory, the UUIDs should be objectGUIDs of the users within the Active Directory.
identityStoreID (integer): The ID of the identity store, from which users will be invited from. The identity store must be already created in the system.
userGroupsIDs (array of integers): The IDs of the user groups, to which the invited users will be assigned. The user groups must be already created in the system. By default, the invited users will be assigned to the default 'Users' user group.

Example of request body:

{
  "uuids": [
    "123e4567-e89b-12d3-a456-426614174000",
    "123e4567-e89b-12d3-a456-426614174001"
  ],
  "identityStoreID": 1,
  "userGroupsIDs": [
    1,
    2,
    3
  ]
}

Response¶

Upon success, the application returns status code 201 Created and in response body JSON data containing the details of the created invitations. The response body will contain an array of objects, where each object represents the details of the created invitation. The response will contain the following fields:

createdBy (object, optional):
- id (integer): The ID of the user that created the invitation.
- title (string, optional): The title of the user that created the invitation.
- name (string): The name of the user that created the invitation.
- surname (string, optional): The surname of the user that created the invitation.
userGroups (array): The groups the user is invited into.
- description (string, optional): The description of the user group.
- name (string): The name of the user group.
- id (integer): The ID of the user group.
phoneNumber (string): The phone number associated with the invitation. countryCode (string): The country code associated with the invitation.
id (integer): The ID of the invitation.
createdBy (integer): The ID of the user who created the invitation.
createdAt (string): The date and time when the invitation was created.
expiresAt (string): The date and time when the invitation will expire.
status (string): The status of the invitation. For possible values see Invitation Statuses.
failedAttempts (integer): The number of failed attempts to accept the invitation.
userID (integer): The ID of the user within the system, to which the invitation is related.
email (string): The email address of the invited user, to which the invitation was sent.
uuid (string): The UUID of the invited user within the identity store.
identityStoreID (integer): The ID of the identity store, where the user was invited from.
tenantID (integer): The ID of the tenant, to which the user was invited. For users invited to the system scope, the value is null.
isRegistered (boolean): Indicates whether the invited user has registered.
verificationCode (string, optional): The verification code associated with the invitation. Only set on invitations to Excalibur local identity store.

Example of response body:

[
  {
    "createdBy": 1,
    "countryCode": "",
    "phoneNumber": "",
    "userGroups": [],
    "id": 2,
    "createdAt": "2025-01-01T00:00:00Z",
    "expiresAt": "2025-01-02T00:00:00Z",
    "status": "pending",
    "failedAttempts": 0,
    "userID": 3,
    "email": "user2@example.com",
    "uuid": "123e4567-e89b-12d3-a456-426614174001",
    "identityStoreID": 123,
    "tenantID": null,
    "isRegistered": false
  },
  {
    "createdBy": 1,
    "countryCode": "",
    "phoneNumber": "",
    "id": 3,
    "createdAt": "2025-01-01T00:00:00Z",
    "expiresAt": "2025-01-02T00:00:00Z",
    "status": "pending",
    "failedAttempts": 0,
    "userID": 4,
    "email": "user3@example.com",
    "uuid": "123e4567-e89b-12d3-a456-426614174002",
    "identityStoreID": 123,
    "tenantID": null,
    "isRegistered": true
  }
]

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X POST {base_url}/api/v1/users/invitations \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "uuids": [
      "123e4567-e89b-12d3-a456-426614174000",
      "123e4567-e89b-12d3-a456-426614174001"
    ],
    "identityStoreID": 1,
    "userGroupsIDs": [
      1,
      2,
      3
    ]   }'

Invite Users to Tenant¶

Endpoint POST /api/v1/tenants/{tenantIdOrSlug}/users/invitations
Permissions: users_invitations_create

This endpoint facilitates the invitation of users to a specific tenant in the Excalibur system.

The rest of its behavior is the same as in Invite Users.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).
Content-Type: application/json Specifies the format of the request payload.

Path Parameters¶

tenantIdOrSlug (string or integer): The unique identifier or slug of the tenant.

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

uuids (array of strings): The UUIDs of the users to be invited. In case the identity store is Active Directory, the UUIDs should be objectGUIDs of the users within the Active Directory.
identityStoreID (integer): The ID of the identity store, from which users will be invited from. The identity store must be already created in the system.
userGroupsIDs (array of integers): The IDs of the user groups, to which the invited users will be assigned. The user groups must be already created in the system. By default, the invited users will be assigned to the default 'Users' user group.

Example of request body:

{
  "uuids": [
    "123e4567-e89b-12d3-a456-426614174000",
    "123e4567-e89b-12d3-a456-426614174001"
  ],
  "identityStoreID": 1,
  "userGroupsIDs": [
    1,
    2,
    3
  ]
}

Response¶

Upon success, the application returns status code 201 Created and in response body JSON data containing the details of the created invitations. The response body will contain an array of objects, where each object represents the details of the created invitation. The response will contain the following fields:

createdBy (object, optional):
- id (integer): The ID of the user that created the invitation.
- title (string, optional): The title of the user that created the invitation.
- name (string): The name of the user that created the invitation.
- surname (string, optional): The surname of the user that created the invitation.
userGroups (array): The groups the user is invited into.
- description (string, optional): The description of the user group.
- name (string): The name of the user group.
- id (integer): The ID of the user group.
phoneNumber (string): The phone number associated with the invitation. countryCode (string): The country code associated with the invitation.
id (integer): The ID of the invitation.
createdBy (integer): The ID of the user who created the invitation.
createdAt (string): The date and time when the invitation was created.
expiresAt (string): The date and time when the invitation will expire.
status (string): The status of the invitation. For possible values see Invitation Statuses.
failedAttempts (integer): The number of failed attempts to accept the invitation.
userID (integer): The ID of the user within the system, to which the invitation is related.
email (string): The email address of the invited user, to which the invitation was sent.
uuid (string): The UUID of the invited user within the identity store.
identityStoreID (integer): The ID of the identity store, where the user was invited from.
tenantID (integer): The ID of the tenant, to which the user was invited.
isRegistered (boolean): Indicates whether the invited user has registered.
verificationCode (string, optional): The verification code associated with the invitation. Only set on invitations to Excalibur local identity store.

Example of response body:

[
  {
    "createdBy": 1,
    "countryCode": "",
    "phoneNumber": "",
    "userGroups": [],
    "id": 2,
    "createdAt": "2025-01-01T00:00:00Z",
    "expiresAt": "2025-01-02T00:00:00Z",
    "status": "pending",
    "failedAttempts": 0,
    "userID": 3,
    "email": "user2@example.com",
    "uuid": "123e4567-e89b-12d3-a456-426614174001",
    "identityStoreID": 123,
    "tenantID": null,
    "isRegistered": false
  },
  {
    "createdBy": 1,
    "countryCode": "",
    "phoneNumber": "",
    "id": 3,
    "createdAt": "2025-01-01T00:00:00Z",
    "expiresAt": "2025-01-02T00:00:00Z",
    "status": "pending",
    "failedAttempts": 0,
    "userID": 4,
    "email": "user3@example.com",
    "uuid": "123e4567-e89b-12d3-a456-426614174002",
    "identityStoreID": 123,
    "tenantID": null,
    "isRegistered": true
  }
]

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X POST {base_url}/api/v1/tenants/{tenantIdOrSlug}/users/invitations \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "uuids": [
      "123e4567-e89b-12d3-a456-426614174000",
      "123e4567-e89b-12d3-a456-426614174001"
    ],
    "identityStoreID": 1,
    "userGroupsIDs": [
      1,
      2,
      3
    ]   }'

Get Invitation¶

Endpoint GET /api/v1/users/invitations/{invitationId}
Permissions: users_invitations_read

This endpoint retrieves the details of a specific invitation by its ID.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

id (integer): The ID of the invitation.

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

N/A: This endpoint does not support request body

Response¶

Upon success, the application returns status code 200 OK and in response body JSON data containing the details of the invitation. The response body will contain the following fields:

id (integer): The ID of the invitation.
createdBy (integer): The ID of the user who created the invitation.
createdAt (string): The date and time when the invitation was created.
expiresAt (string): The date and time when the invitation will expire.
status (string): The status of the invitation. For possible values see Invitation Statuses.
failedAttempts (integer): The number of failed attempts to accept the invitation.
userID (integer): The ID of the user within the system, to which the invitation is related.
email (string): The email address of the invited user, to which the invitation was sent.
uuid (string): The UUID of the invited user within the identity store.
identityStoreID (integer): The ID of the identity store, where the user was invited from.
tenantID (integer): The ID of the tenant, to which the user was invited. For users invited to system scope, this value is null.
verificationCode (string, optional): The verification code associated with the invitation. Only set on invitations to Excalibur local identity store.

Example of response body:

{
  "id": 3,
  "createdBy": 1,
  "createdAt": "2025-01-01T00:00:00Z",
  "expiresAt": "2025-01-02T00:00:00Z",
  "status": "pending",
  "failedAttempts": 0,
  "userID": 3,
  "email": "user3@example.com",
  "uuid": "123e4567-e89b-12d3-a456-426614174002",
  "identityStoreID": 3,
  "tenantID": null
}

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X GET {base_url}/api/v1/users/invitations/3

Get Invitation from Tenant¶

Endpoint GET /api/v1/tenants/{tenantIdOrSlug}/users/invitations/{id}
Permissions: users_invitations_read

This endpoint retrieves the details of the invitation with the specified ID for a specific tenant.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

tenantIdOrSlug (string or integer): The unique identifier or slug of the tenant.
id (integer): The ID of the invitation.

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

N/A: This endpoint does not support request body

Response¶

Upon success, the application returns status code 200 OK and in response body JSON data containing the details of the invitation. The response body will contain the following fields:

id (integer): The ID of the invitation.
createdBy (integer): The ID of the user who created the invitation.
createdAt (string): The date and time when the invitation was created.
expiresAt (string): The date and time when the invitation will expire.
status (string): The status of the invitation. For possible values see Invitation Statuses.
failedAttempts (integer): The number of failed attempts to accept the invitation.
userID (integer): The ID of the user within the system, to which the invitation is related.
email (string): The email address of the invited user, to which the invitation was sent.
uuid (string): The UUID of the invited user within the identity store.
identityStoreID (integer): The ID of the identity store, where the user was invited from.
tenantID (integer): The ID of the tenant, to which the user was invited. For users invited to system scope, this value is null.
verificationCode (string, optional): The verification code associated with the invitation. Only set on invitations to Excalibur local identity store.

Example of response body:

{
  "id": 3,
  "createdBy": 1,
  "createdAt": "2025-01-01T00:00:00Z",
  "expiresAt": "2025-01-02T00:00:00Z",
  "status": "pending",
  "failedAttempts": 0,
  "userID": 3,
  "email": "user3@example.com",
  "uuid": "123e4567-e89b-12d3-a456-426614174002",
  "identityStoreID": 3,
  "tenantID": null
}

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X GET {base_url}/api/v1/tenants/1/users/invitations/3

GET Invitation Link¶

Endpoint GET /api/v1/users/invitations/{id}/link
Permissions: users_invitations_read

This endpoint retrieves the link of a specific invitation by its unique ID.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

id (integer): The ID of the invitation.

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

N/A: This endpoint does not support request body

Response¶

Upon success, the application returns status code 200 OK and in response body JSON data containing the link of invitation.

link (string): The ID of the invitation.

Example of response body:

{
  "link": "https://{base_url}/register?invitation=abcdefgh"
}

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X GET {base_url}/api/v1/users/invitations/1/link

GET Invitation Link from Tenant¶

Endpoint GET /api/v1/tenants/{tenantIdOrSlug}/users/invitations/{id}/link
Permissions: users_invitations_read

This endpoint retrieves invitation detail for a specific tenant in the system.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

tenantIdOrSlug (string or integer): The unique identifier or slug of the tenant.
id (integer): The ID of the invitation.

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

N/A: This endpoint does not support request body

Response¶

Upon success, the application returns status code 200 OK and in response body JSON data containing the link of invitation.

link (string): The ID of the invitation.

Example of response body:

{
  "link": "https://{base_url}/register?invitation=abcdefgh"
}

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X GET {base_url}/api/v1/tenants/1/users/invitations/2/link

Get List of Invitations Detail¶

Endpoint GET /api/v1/users/invitations/detail
Permissions: users_invitations_read

This endpoint retrieves a list of invitations in detail. The response includes pagination support through limit and offset parameters, allowing clients to control the number of returned users and the starting point for retrieval. Additionally, filtering, sorting, and specific column selection can be applied to customize the response.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

N/A: This endpoint does not support request body

Query Parameters¶

This endpoint supports filtering, pagination and sorting as described in Excalibur v4 API Query Parameters section.

Request Body¶

N/A: This endpoint does not support request body

Response¶

Upon success, the application returns status code 200 OK and in response body JSON data containing the details of the invitation. The response body will contain the following fields:

total (integer): The total number of invitations.
entities (array): A list of invitations, each with the following parameters:
- createdBy (object, optional):
  - id (integer): The ID of the user that created the invitation.
  - title (string, optional): The title of the user that created the invitation.
  - name (string): The name of the user that created the invitation.
  - surname (string, optional): The surname of the user that created the invitation.
- userGroups (array): The groups the user is invited into.
  - description (string, optional): The description of the user group.
  - name (string): The name of the user group.
  - id (integer): The ID of the user group.
- phoneNumber (string): The phone number associated with the invitation. countryCode (string): The country code associated with the invitation.
- id (integer): The ID of the invitation.
- createdBy (integer): The ID of the user who created the invitation.
- createdAt (string): The date and time when the invitation was created.
- expiresAt (string): The date and time when the invitation will expire.
- status (string): The status of the invitation. For possible values see Invitation Statuses.
- failedAttempts (integer): The number of failed attempts to accept the invitation.
- userID (integer): The ID of the user within the system, to which the invitation is related.
- email (string): The email address of the invited user, to which the invitation was sent.
- uuid (string): The UUID of the invited user within the identity store.
- identityStoreID (integer): The ID of the identity store, where the user was invited from.
- tenantID (integer): The ID of the tenant, to which the user was invited.
- isRegistered (boolean): Indicates whether the invited user has registered.
- verificationCode (string, optional): The verification code associated with the invitation. Only set on invitations to Excalibur local identity store.

Example of response body:

{
  "total": 1,
  "entities": [
    {
      "createdBy": 1,
      "countryCode": "",
      "phoneNumber": "",
      "userGroups": [],
      "id": 2,
      "createdAt": "2025-01-01T00:00:00Z",
      "expiresAt": "2025-01-02T00:00:00Z",
      "status": "pending",
      "failedAttempts": 0,
      "userID": 3,
      "email": "user2@example.com",
      "uuid": "123e4567-e89b-12d3-a456-426614174001",
      "identityStoreID": 2,
      "tenantID": null,
      "isRegistered": false
    }
  ]
}

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X GET {base_url}/api/v1/users/invitations/detail

Get List of Invitations Detail from Tenant¶

Endpoint GET /api/v1/tenants/{tenantIdOrSlug}/users/invitations/detail
Permissions: users_invitations_read

This endpoint retrieves the details of the invitation with the specified ID for a specific tenant.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

tenantIdOrSlug (string or integer): The unique identifier or slug of the tenant.

Query Parameters¶

This endpoint supports filtering, pagination and sorting as described in Excalibur v4 API Query Parameters section.

Request Body¶

N/A: This endpoint does not support request body

Response¶

Upon success, the application returns status code 200 OK and in response body JSON data containing the details of the invitation. The response body will contain the following fields:

total (integer): The total number of invitations.
entities (array): A list of invitations, each with the following parameters:
- createdBy (object, optional):
  - id (integer): The ID of the user that created the invitation.
  - title (string, optional): The title of the user that created the invitation.
  - name (string): The name of the user that created the invitation.
  - surname (string, optional): The surname of the user that created the invitation.
- userGroups (array): The groups the user is invited into.
  - description (string, optional): The description of the user group.
  - name (string): The name of the user group.
  - id (integer): The ID of the user group.
- phoneNumber (string): The phone number associated with the invitation. countryCode (string): The country code associated with the invitation.
- id (integer): The ID of the invitation.
- createdBy (integer): The ID of the user who created the invitation.
- createdAt (string): The date and time when the invitation was created.
- expiresAt (string): The date and time when the invitation will expire.
- status (string): The status of the invitation. For possible values see Invitation Statuses.
- failedAttempts (integer): The number of failed attempts to accept the invitation.
- userID (integer): The ID of the user within the system, to which the invitation is related.
- email (string): The email address of the invited user, to which the invitation was sent.
- uuid (string): The UUID of the invited user within the identity store.
- identityStoreID (integer): The ID of the identity store, where the user was invited from.
- tenantID (integer): The ID of the tenant, to which the user was invited.
- isRegistered (boolean): Indicates whether the invited user has registered.
- verificationCode (string, optional): The verification code associated with the invitation. Only set on invitations to Excalibur local identity store.

Example of response body:

{
  "total": 1,
  "entities": [
    {
      "createdBy": 1,
      "countryCode": "",
      "phoneNumber": "",
      "userGroups": [],
      "id": 2,
      "createdAt": "2025-01-01T00:00:00Z",
      "expiresAt": "2025-01-02T00:00:00Z",
      "status": "pending",
      "failedAttempts": 0,
      "userID": 3,
      "email": "user2@example.com",
      "uuid": "123e4567-e89b-12d3-a456-426614174001",
      "identityStoreID": 2,
      "tenantID": null,
      "isRegistered": false
    }
  ]
}

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X GET {base_url}/api/v1/tenants/1/users/invitations/detail

Delete Invitation¶

Endpoint DELETE /api/v1/users/invitations/{id}
Permissions: users_invitations_delete

This endpoint sets invitation status (see Invitation Statuses) as dismissed.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

id (integer): The ID of the invitation.

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

N/A: This endpoint does not support request body

Response¶

Upon success, the application returns status code 204 No Content.

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X DELETE {base_url}/api/v1/users/invitations/3

Delete Invitation from Tenant¶

Endpoint DELETE /api/v1/tenants/{tenantIdOrSlug}/users/invitations/{id}
Permissions: users_invitations_delete

This endpoint sets invitation status (see Invitation Statuses) as dismissed in a specific tenant.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

tenantIdOrSlug (string or integer): The unique identifier or slug of the tenant.
id (integer): The ID of the invitation.

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

N/A: This endpoint does not support request body

Response¶

Upon success, the application returns status code 204 No Content.

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X DELETE {base_url}/api/v1/tenants/my-tenant/users/invitations/3 \
  -H "Authorization: Bearer {access_token}"

Delete Multiple Invitations¶

Endpoint DELETE /api/v1/users/invitations
Permissions: users_invitations_delete

This endpoint allows for dismissal of multiple user invitations, by setting their status to dismissed (see Invitation Statuses).

It expects an array of invitation IDs to be provided via the query parameter.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

N/A: This endpoint does not utilize path parameters.

Query Parameters¶

ids (array of integers): The unique identifiers of the invitations to be deleted.

Request Body¶

N/A: This endpoint does not support request body

Response¶

Upon success, the application returns status code 204 No Content.

If no IDs are provided, a 422 Unprocessable Entity error is returned.

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X DELETE {base_url}/api/v1/users/invitations?ids[]=123&ids[]=456&ids[]=789 \
  -H "Authorization: Bearer {access_token}"

Delete Multiple Invitations from Tenant¶

Endpoint DELETE /api/v1/tenants/{tenantIdOrSlug}/users/invitations
Permissions: users_invitations_delete

This endpoint allows for dismissal of multiple user invitations for a specific tenant, by setting their status to dismissed (see Invitation Statuses).

It expects an array of invitation IDs to be provided via the query parameter.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

tenantIdOrSlug (string or integer): The unique identifier or slug of the tenant.

Query Parameters¶

ids (array of integers): The unique identifiers of the invitations to be deleted.

Request Body¶

N/A: This endpoint does not support request body

Response¶

Upon success, the application returns status code 204 No Content.

If no IDs are provided, a 422 Unprocessable Entity error is returned.

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X DELETE {base_url}/api/v1/tenants/{tenantIdOrSlug}/users/invitations?ids[]=123&ids[]=456&ids[]=789 \
  -H "Authorization: Bearer {access_token}"

PAM Target Management¶

Privileged Access Management (PAM) is the most effective solution to safeguard privileged accounts and sensitive resources within an organization. PAM focuses on controlling and monitoring access to critical systems, applications, and data by ensuring that only authorized users can access these resources under secure and auditable conditions.

Excalibur v4 incorporates PAM as a seamlessly integrated module, enabling companies to manage privileged access to their sensitive systems efficiently. Key features of PAM in Excalibur include

Target Management Administrators can define and manage PAM targets, such as Remote Desktop Protocol (RDP), Secure Shell (SSH), Virtual Network Computing (VNC) and Web connections. Each target is configured with specific security, monitoring, and operational policies.
Session Control and Monitoring PAM ensures secure, auditable access to privileged accounts. All privileged sessions are logged, and optional session recording provides a playback capability for audit and compliance purposes.
Customizable Policies Administrators can define granular access policies for each target. Policies can include session recording, clipboard control, file transfer permissions, and advanced security settings like certificate validation.
User Management Administrators can assign users or groups to PAM targets with clearly defined roles and permissions. Multi-factor authentication (MFA) and just-in-time access further enhance the security of privileged accounts.
Integration with the Excalibur Ecosystem PAM seamlessly integrates with other Excalibur v4 modules, such as Multi-Factor Authentication (MFA) and geofencing, to provide context-aware access control. Centralized dashboards enable a unified view of privileged access activity across the entire organization.

By incorporating PAM into the Excalibur v4 application, organizations can confidently manage privileged access, ensuring both security and operational efficiency while complying with stringent regulatory requirements.

Add RDP PAM Target¶

Endpoint POST /api/v1/pam/targets/rdp
Permissions: pam_targets_create

This endpoint enables clients to securely add a new Remote Desktop Protocol (RDP) PAM target to the system. The RDP target can be configured with advanced settings like session recording, clipboard management, and file transfer controls to ensure security and usability.

Upon successful creation, the RDP target is available for secure session initiation through the Excalibur dashboard interface after successful user authentication.

Supported Security Modes

The security parameter determines the level of security for the RDP connection.

any: Accepts any available security protocol for the connection, prioritizing compatibility.
nla: Enforces Network Level Authentication, ensuring users are authenticated before the RDP session is established.
nla-ext: Extends nla with additional security enhancements for enterprise environments.
tls: Uses Transport Layer Security to encrypt the connection.
wmconnect: Employs the Windows Media protocol for specific RDP applications.
rdp: Falls back to the older RDP protocol. Not recommended due to weaker security.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).
Content-Type: application/json Specifies the format of the request payload.

Path Parameters¶

N/A: This endpoint does not utilize path parameters.

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

(object or array):
- name (string): The name of the RDP target, used for identification in the system. (Required)
- description (string): An optional description of the RDP target to provide context. (Optional)
- hostname (string): The hostname or IP address of the RDP server. (Required)
- port (integer): The port for the RDP service, typically 3389. (Required)
- username (string): The username used for authentication to the RDP target. (Optional)
- password (string): The password associated with the provided username. (Optional)
- domain (string): Domain for RDP authentication. (Optional)
- security (string): The security mode for the RDP connection. (Required)
- ignoreCertificate (boolean): Whether to bypass SSL certificate validation for the connection. (Required)
- authorizationRequired (boolean): Whether QR-based authorization is required. (Required)
- useExcaliburCredentials (boolean): Whether credentials managed by Excalibur are used. (Required)
- tunnelID (integer): The ID of the tunnel to use for the connection. Default is null (no tunnel). (Optional)
- clipboard (object): Clipboard configuration settings. (Required)
  - enableCopy (boolean): Allows copying to the remote session. (Required)
  - enablePaste (boolean): Allows pasting from the remote session to the client. (Required)
- fileTransfer (object): File transfer configuration settings. (Required)
  - uploadEnabled (boolean): Allows file uploads to the remote session. (Required)
  - downloadEnabled (boolean): Allows file downloads from the remote session. (Required)
  - uploadFileSizeLimit (number): Maximum file size for uploads in bytes. Default is null (no limit). (Optional)
- recording (object): Session recording settings. (Required)
  - enabled (boolean): Enables recording for the session. (Required)
  - retentionPeriod (number): The retention period for session recordings in minutes. null indicates unlimited retention. (Optional)
- remoteApplication (object): Remote application settings, if applicable. (Optional)
  - name (string): The name of the remote application to be launched. (Required)
  - workingDirectory (string): The working directory for the remote application. (Required)
  - commandLineArguments (string): Command-line arguments for launching the application. (Required)

Example of request body with single target:

{
  "name": "Corporate RDP Server",
  "description": "RDP target for secure corporate network access",
  "hostname": "rdp.example.com",
  "port": 3389,
  "username": "admin",
  "password": "securePassword123!",
  "domain": "CORP",
  "security": "nla",
  "ignoreCertificate": true,
  "clipboard": {
    "enableCopy": true,
    "enablePaste": true
  },
  "fileTransfer": {
    "uploadEnabled": true,
    "downloadEnabled": true,
    "uploadFileSizeLimit": 10485760,
    "rootDirectory": "/home/admin/uploads"
  },
  "recording": {
    "enabled": true,
    "retentionPeriod": 4320
  },
  "authorizationRequired": true,
  "useExcaliburCredentials": false,
  "remoteApplication": {
    "name": "Microsoft Word",
    "workingDirectory": "C:\\Program Files\\Microsoft Office",
    "commandLineArguments": "/safe"
  }
}

Example of request body with multiple targets:

[
  {
    "name": "Corporate RDP Server",
    "description": "RDP target for secure corporate network access",
    "hostname": "rdp.example.com",
    "port": 3389,
    "username": "admin",
    "password": "securePassword123!",
    "domain": "CORP",
    "security": "nla",
    "ignoreCertificate": true,
    "clipboard": {
      "enableCopy": true,
      "enablePaste": true
    },
    "fileTransfer": {
      "uploadEnabled": true,
      "downloadEnabled": true,
      "uploadFileSizeLimit": 10485760,
      "rootDirectory": "/home/admin/uploads"
    },
    "recording": {
      "enabled": true,
      "retentionPeriod": 4320
    },
    "authorizationRequired": true,
    "useExcaliburCredentials": false,
    "remoteApplication": {
      "name": "Microsoft Word",
      "workingDirectory": "C:\\Program Files\\Microsoft Office",
      "commandLineArguments": "/safe"
    }
  },
  {
    "name": "Corporate RDP Server",
    "description": "RDP target for secure corporate network access",
    "hostname": "rdp.example.com",
    "port": 3389,
    "username": "admin",
    "password": "securePassword123!",
    "domain": "CORP",
    "security": "nla",
    "ignoreCertificate": true,
    "clipboard": {
      "enableCopy": false,
      "enablePaste": false
    },
    "fileTransfer": {
      "uploadEnabled": false,
      "downloadEnabled": false
    },
    "recording": {
      "enabled": true,
      "retentionPeriod": 4320
    },
    "authorizationRequired": true,
    "useExcaliburCredentials": false
  }
]

Response¶

Upon success, the application returns status code 201 Created and in response body JSON data containing the following parameters:

ids (array of integers): unique IDs of the newly created PAM targets

Example of response body:

{
  "ids": [
    1234
  ]
}

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X POST "{base_url}/api/v1/pam/rdp-targets" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Corporate RDP Server",
    "description": "RDP target for corporate network access",
    "hostname": "rdp.example.com",
    "port": 3389,
    "username": "admin",
    "password": "securePassword123",
    "domain": "CORP",
    "security": "nla",
    "ignoreCertificate": true,
    "clipboard": {
      "enableCopy": true,
      "enablePaste": false
    },
    "fileTransfer": {
      "uploadEnabled": true,
      "downloadEnabled": false,
      "uploadFileSizeLimit": 10485760,
      "rootDirectory": "/home/admin/uploads"
    },
    "recording": {
      "enabled": true,
      "retentionPeriod": 4320
    }
  }'

Add RDP PAM Target to Tenant¶

Endpoint POST /api/v1/tenants/{tenantIdOrSlug}/pam/targets/rdp
Permissions: pam_targets_create

This endpoint enables clients to securely add a new Remote Desktop Protocol (RDP) PAM target to the system. The RDP target can be configured with advanced settings like session recording, clipboard management, and file transfer controls to ensure security and usability.

Upon successful creation, the RDP target is available for secure session initiation through the Excalibur dashboard interface after successful user authentication.

Supported Security Modes

The security parameter determines the level of security for the RDP connection.

any: Accepts any available security protocol for the connection, prioritizing compatibility.
nla: Enforces Network Level Authentication, ensuring users are authenticated before the RDP session is established.
nla-ext: Extends nla with additional security enhancements for enterprise environments.
tls: Uses Transport Layer Security to encrypt the connection.
wmconnect: Employs the Windows Media protocol for specific RDP applications.
rdp: Falls back to the older RDP protocol. Not recommended due to weaker security.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).
Content-Type: application/json Specifies the format of the request payload.

Path Parameters¶

tenantIdOrSlug (string or integer): The unique identifier or slug of the tenant.

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

(object or array):
- name (string): The name of the RDP target, used for identification in the system. (Required)
- description (string): An optional description of the RDP target to provide context. (Optional)
- hostname (string): The hostname or IP address of the RDP server. (Required)
- port (integer): The port for the RDP service, typically 3389. (Required)
- username (string): The username used for authentication to the RDP target. (Optional)
- password (string): The password associated with the provided username. (Optional)
- domain (string): Domain for RDP authentication. (Optional)
- security (string): The security mode for the RDP connection. (Required)
- ignoreCertificate (boolean): Whether to bypass SSL certificate validation for the connection. (Required)
- authorizationRequired (boolean): Whether QR-based authorization is required. (Required)
- useExcaliburCredentials (boolean): Whether credentials managed by Excalibur are used. (Required)
- tunnelID (integer): The ID of the tunnel to use for the connection. Default is null (no tunnel). (Optional)
- clipboard (object): Clipboard configuration settings. (Required)
  - enableCopy (boolean): Allows copying to the remote session. (Required)
  - enablePaste (boolean): Allows pasting from the remote session to the client. (Required)
- fileTransfer (object): File transfer configuration settings. (Required)
  - uploadEnabled (boolean): Allows file uploads to the remote session. (Required)
  - downloadEnabled (boolean): Allows file downloads from the remote session. (Required)
  - uploadFileSizeLimit (number): Maximum file size for uploads in bytes. Default is null (no limit). (Optional)
- recording (object): Session recording settings. (Required)
  - enabled (boolean): Enables recording for the session. (Required)
  - retentionPeriod (number): The retention period for session recordings in minutes. null indicates unlimited retention. (Optional)
- remoteApplication (object): Remote application settings, if applicable. (Optional)
  - name (string): The name of the remote application to be launched. (Required)
  - workingDirectory (string): The working directory for the remote application. (Required)
  - commandLineArguments (string): Command-line arguments for launching the application. (Required)

Example of request body with single target:

{
  "name": "Corporate RDP Server",
  "description": "RDP target for secure corporate network access",
  "hostname": "rdp.example.com",
  "port": 3389,
  "username": "admin",
  "password": "securePassword123!",
  "domain": "CORP",
  "security": "nla",
  "ignoreCertificate": true,
  "clipboard": {
    "enableCopy": true,
    "enablePaste": true
  },
  "fileTransfer": {
    "uploadEnabled": true,
    "downloadEnabled": true,
    "uploadFileSizeLimit": 10485760,
    "rootDirectory": "/home/admin/uploads"
  },
  "recording": {
    "enabled": true,
    "retentionPeriod": 4320
  },
  "authorizationRequired": true,
  "useExcaliburCredentials": false,
  "remoteApplication": {
    "name": "Microsoft Word",
    "workingDirectory": "C:\\Program Files\\Microsoft Office",
    "commandLineArguments": "/safe"
  }
}

Example of request body with multiple targets:

[
  {
    "name": "Corporate RDP Server",
    "description": "RDP target for secure corporate network access",
    "hostname": "rdp.example.com",
    "port": 3389,
    "username": "admin",
    "password": "securePassword123!",
    "domain": "CORP",
    "security": "nla",
    "ignoreCertificate": true,
    "clipboard": {
      "enableCopy": true,
      "enablePaste": true
    },
    "fileTransfer": {
      "uploadEnabled": true,
      "downloadEnabled": true,
      "uploadFileSizeLimit": 10485760,
      "rootDirectory": "/home/admin/uploads"
    },
    "recording": {
      "enabled": true,
      "retentionPeriod": 4320
    },
    "authorizationRequired": true,
    "useExcaliburCredentials": false,
    "remoteApplication": {
      "name": "Microsoft Word",
      "workingDirectory": "C:\\Program Files\\Microsoft Office",
      "commandLineArguments": "/safe"
    }
  },
  {
    "name": "Corporate RDP Server",
    "description": "RDP target for secure corporate network access",
    "hostname": "rdp.example.com",
    "port": 3389,
    "username": "admin",
    "password": "securePassword123!",
    "domain": "CORP",
    "security": "nla",
    "ignoreCertificate": true,
    "clipboard": {
      "enableCopy": false,
      "enablePaste": false
    },
    "fileTransfer": {
      "uploadEnabled": false,
      "downloadEnabled": false
    },
    "recording": {
      "enabled": true,
      "retentionPeriod": 4320
    },
    "authorizationRequired": true,
    "useExcaliburCredentials": false
  }
]

Response¶

Upon success, the application returns status code 201 Created and in response body JSON data containing the following parameters:

ids (array of integers): unique IDs of the newly created PAM targets

Example of response body:

{
  "ids": [
    1234
  ]
}

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X POST "{base_url}/api/v1/tenants/my-tenant/pam/targets/rdp" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Corporate RDP Server",
    "description": "RDP target for corporate network access",
    "hostname": "rdp.example.com",
    "port": 3389,
    "username": "admin",
    "password": "securePassword123",
    "domain": "CORP",
    "security": "nla",
    "ignoreCertificate": true,
    "clipboard": {
      "enableCopy": true,
      "enablePaste": false
    },
    "fileTransfer": {
      "uploadEnabled": true,
      "downloadEnabled": false,
      "uploadFileSizeLimit": 10485760,
      "rootDirectory": "/home/admin/uploads"
    },
    "recording": {
      "enabled": true,
      "retentionPeriod": 4320
    }
  }'

Update RDP PAM Target¶

Endpoint PATCH /api/v1/pam/targets/rdp/{id}
Permissions: pam_targets_update

This endpoint allows clients to update the configuration details of an existing RDP PAM target. Administrators can modify various parameters such as hostname, credentials, and security settings. Any changes made will apply to new sessions, while ongoing sessions remain unaffected.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).
Content-Type: application/json Specifies the format of the request payload.

Path Parameters¶

id (integer): The unique identifier of the RDP PAM target to be updated. (Required)

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

Provide the fields you want to update in the request body. Fields not included in the request will remain unchanged.

name (string): The name of the RDP target, used for identification in the system. (Optional)
description (string): A description of the RDP target. (Optional)
hostname (string): The hostname or IP address of the RDP server. (Optional)
port (integer): The port for the RDP service, typically 3389. (Optional)
username (string): The username used for authentication to the RDP target. (Optional)
password (string): The password associated with the provided username. (Optional)
domain (string): Domain for RDP authentication. (Optional)
security (string): The security mode for the RDP connection. (Optional)
ignoreCertificate (boolean): Whether to bypass SSL certificate validation for the connection. (Optional)
clipboard (object): Clipboard configuration settings. (Optional)
- enableCopy (boolean): Allows copying to the remote session. Default is true. (Optional)
- enablePaste (boolean): Allows pasting from the remote session to the client. Default is true. (Optional)
fileTransfer (object): File transfer configuration settings. (Optional)
- uploadEnabled (boolean): Allows file uploads to the remote session. Default is true. (Optional)
- downloadEnabled (boolean): Allows file downloads from the remote session. The default is false. (Optional)
- uploadFileSizeLimit (number): Maximum file size for uploads in bytes. Default is null (no limit). (Optional)
- rootDirectory (string): Specifies the root directory for file transfers on the remote system. (Optional)
recording (object): Session recording settings. (Optional)
- enabled (boolean): Enables recording for the session. The default is false. (Optional)
- retentionPeriod (number): The retention period for session recordings in minutes. Default is null (unlimited retention). (Optional)
authorizationRequired (boolean): Whether QR-based authorization is required. (Optional)
useExcaliburCredentials (boolean): Whether credentials managed by Excalibur are used. (Optional)
remoteApplication (object): Remote application settings. (Optional)
- name (string): The name of the remote application to be launched. (Optional)
- workingDirectory (string): The working directory for the remote application. (Optional)
- commandLineArguments (string): Command-line arguments for launching the application. (Optional)
tunnelID (integer): The ID of the tunnel to use for the connection. Default is null (no tunnel). (Optional)

Response¶

Upon success, the application returns status code 204 No Content, indicating that the RDP PAM target has been successfully updated.

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X PATCH {base_url}/api/v1/pam/targets/rdp/1234 \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Corporate RDP Server Updated",
    "hostname": "updated-rdp.example.com",
    "username": "newAdmin",
    "password": "newSecurePassword123!",
    "security": "tls",
    "clipboard": {
      "enableCopy": false,
      "enablePaste": true
    },
    "fileTransfer": {
      "uploadEnabled": false,
      "downloadEnabled": true
    },
    "recording": {
      "enabled": true,
      "retentionPeriod": 720
    }
  }'

Update RDP PAM Target in Tenant¶

Endpoint PATCH /api/v1/tenants/{tenantIdOrSlug}/pam/targets/rdp/{id}
Permissions: pam_targets_update

This endpoint allows clients to update the configuration details of an existing RDP PAM target. Administrators can modify various parameters such as hostname, credentials, and security settings. Any changes made will apply to new sessions, while ongoing sessions remain unaffected.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).
Content-Type: application/json Specifies the format of the request payload.

Path Parameters¶

tenantIdOrSlug (string or integer): The unique identifier or slug of the tenant.
id (integer): The unique identifier of the RDP PAM target to be updated. (Required)

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

Provide the fields you want to update in the request body. Fields not included in the request will remain unchanged.

name (string): The name of the RDP target, used for identification in the system. (Optional)
description (string): A description of the RDP target. (Optional)
hostname (string): The hostname or IP address of the RDP server. (Optional)
port (integer): The port for the RDP service, typically 3389. (Optional)
username (string): The username used for authentication to the RDP target. (Optional)
password (string): The password associated with the provided username. (Optional)
domain (string): Domain for RDP authentication. (Optional)
security (string): The security mode for the RDP connection. (Optional)
ignoreCertificate (boolean): Whether to bypass SSL certificate validation for the connection. (Optional)
clipboard (object): Clipboard configuration settings. (Optional)
- enableCopy (boolean): Allows copying to the remote session. Default is true. (Optional)
- enablePaste (boolean): Allows pasting from the remote session to the client. Default is true. (Optional)
fileTransfer (object): File transfer configuration settings. (Optional)
- uploadEnabled (boolean): Allows file uploads to the remote session. Default is true. (Optional)
- downloadEnabled (boolean): Allows file downloads from the remote session. The default is false. (Optional)
- uploadFileSizeLimit (number): Maximum file size for uploads in bytes. Default is null (no limit). (Optional)
- rootDirectory (string): Specifies the root directory for file transfers on the remote system. (Optional)
recording (object): Session recording settings. (Optional)
- enabled (boolean): Enables recording for the session. The default is false. (Optional)
- retentionPeriod (number): The retention period for session recordings in minutes. Default is null (unlimited retention). (Optional)
authorizationRequired (boolean): Whether QR-based authorization is required. (Optional)
useExcaliburCredentials (boolean): Whether credentials managed by Excalibur are used. (Optional)
remoteApplication (object): Remote application settings. (Optional)
- name (string): The name of the remote application to be launched. (Optional)
- workingDirectory (string): The working directory for the remote application. (Optional)
- commandLineArguments (string): Command-line arguments for launching the application. (Optional)
tunnelid (integer): The ID of the tunnel to use for the connection. Default is null (no tunnel). (Optional)

Response¶

Upon success, the application returns status code 204 No Content, indicating that the RDP PAM target has been successfully updated.

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X PATCH {base_url}/api/v1/tenants/my-tenant/pam/targets/rdp/1234 \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Corporate RDP Server Updated",
    "hostname": "updated-rdp.example.com",
    "username": "newAdmin",
    "password": "newSecurePassword123!",
    "security": "tls",
    "clipboard": {
      "enableCopy": false,
      "enablePaste": true
    },
    "fileTransfer": {
      "uploadEnabled": false,
      "downloadEnabled": true
    },
    "recording": {
      "enabled": true,
      "retentionPeriod": 720
    }
  }'

Add SSH PAM Target¶

Endpoint POST /api/v1/pam/targets/ssh
Permissions: pam_targets_create

This endpoint enables clients to securely add a new Secure Shell (SSH) PAM target to the system. The SSH target can be configured with advanced settings like session recording, file transfer management, and key-based authentication to ensure security and usability.

Upon successful creation, the SSH target is available for secure session initiation through the Excalibur dashboard interface after successful user authentication.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).
Content-Type: application/json Specifies the format of the request payload.

Path Parameters¶

N/A: This endpoint does not utilize path parameters.

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

(object or array):
- name (string): The name of the SSH target, used for identification in the system. (Required)
- description (string): An optional description of the SSH target to provide context. (Optional)
- hostname (string): The hostname or IP address of the SSH server. (Required)
- port (integer): The port for the SSH service, typically 22. (Required)
- username (string): The username used for authentication to the SSH target. (Optional)
- password (string): The password associated with the provided username. (Optional)
- privateKey (string): The private key for key-based SSH authentication. (Optional)
- passphrase (string): The passphrase for the private key, if applicable. (Optional)
- useExcaliburCredentials (boolean): Whether to use credentials managed by Excalibur. The default is false. (Optional)
- authorizationRequired (boolean): Whether QR-based authorization is required. (Optional)
- tunnelID (integer): The ID of the tunnel to use for the connection. Default is null (no tunnel). (Optional)
- clipboard (object): Clipboard configuration settings. (Required)
  - enableCopy (boolean): Allows copying to the remote session. (Required)
  - enablePaste (boolean): Allows pasting from the remote session to the client. (Required)
- fileTransfer (object): File transfer configuration settings. (Optional)
  - uploadEnabled (boolean): Allows file uploads to the remote session. (Required)
  - downloadEnabled (boolean): Allows file downloads from the remote session. (Required)
  - uploadFileSizeLimit (number): Maximum file size for uploads in bytes. The default is null (no limit). (Optional)
  - rootDirectory (string): Specifies the root directory for file transfers on the remote system. Default is the user's home directory. (Optional)
- recording (object): Session recording settings. (Required)
  - enabled (boolean): Enables recording for the session. The default is false. (Required)
  - retentionPeriod (number): The retention period for session recordings in minutes. null indicates unlimited retention. (Optional)

Example of Request Body with single target:

{
  "name": "Corporate SSH Server",
  "description": "SSH target for secure corporate network access",
  "hostname": "ssh.example.com",
  "port": 22,
  "username": "admin",
  "password": "securePassword123!",
  "useExcaliburCredentials": false,
  "authorizationRequired": true,
  "fileTransfer": {
    "uploadEnabled": true,
    "downloadEnabled": true,
    "uploadFileSizeLimit": 10485760,
    "rootDirectory": "/home/admin/uploads"
  },
  "recording": {
    "enabled": true,
    "retentionPeriod": 4320
  }
}

Example of Request Body with multiple targets:

[
  {
    "name": "Corporate SSH Server",
    "description": "SSH target for secure corporate network access",
    "hostname": "ssh.example.com",
    "port": 22,
    "username": "admin",
    "password": "securePassword123!",
    "useExcaliburCredentials": false,
    "authorizationRequired": true,
    "fileTransfer": {
      "uploadEnabled": true,
      "downloadEnabled": true,
      "uploadFileSizeLimit": 10485760,
      "rootDirectory": "/home/admin/uploads"
    },
    "recording": {
      "enabled": true,
      "retentionPeriod": 4320
    }
  },
  {
    "name": "Corporate SSH Server 2",
    "description": "SSH target for secure corporate network access",
    "hostname": "ssh2.example.com",
    "port": 22,
    "username": "admin2",
    "password": "securePassword123!",
    "useExcaliburCredentials": false,
    "authorizationRequired": false,
    "fileTransfer": {
      "uploadEnabled": false,
      "downloadEnabled": false
    },
    "recording": {
      "enabled": false
    }
  }
]

Response¶

Upon success, the application returns status code 201 Created and in the response body JSON data containing the following parameter:

ids (array of integers): Unique IDs of the newly created PAM targets.

Example of Response Body:

{
  "ids": [
    5678
  ]
}

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X POST {base_url}/api/v1/pam/targets/ssh \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Corporate SSH Server",
    "description": "SSH target for secure corporate network access",
    "hostname": "ssh.example.com",
    "port": 22,
    "username": "admin",
    "privateKey": "-----BEGIN PRIVATE KEY-----\\nMIIEvQIBADANBgkq...\\n-----END PRIVATE KEY-----",
    "passphrase": "newPassphrase",
    "useExcaliburCredentials": false,
    "authorizationRequired": true,
    "fileTransfer": {
      "uploadEnabled": true,
      "downloadEnabled": true,
      "uploadFileSizeLimit": 10485760,
      "rootDirectory": "/home/admin/uploads"
    },
    "recording": {
      "enabled": true,
      "retentionPeriod": 4320
    }
  }'

Add SSH PAM Target to Tenant¶

Endpoint POST /api/v1/tenants/{tenantIdOrSlug}/pam/targets/ssh
Permissions: pam_targets_create

This endpoint enables clients to securely add a new Secure Shell (SSH) PAM target to the system. The SSH target can be configured with advanced settings like session recording, file transfer management, and key-based authentication to ensure security and usability.

Upon successful creation, the SSH target is available for secure session initiation through the Excalibur dashboard interface after successful user authentication.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).
Content-Type: application/json Specifies the format of the request payload.

Path Parameters¶

tenantIdOrSlug (string or integer): The unique identifier or slug of the tenant.

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

(object or array):
- name (string): The name of the SSH target, used for identification in the system. (Required)
- description (string): An optional description of the SSH target to provide context. (Optional)
- hostname (string): The hostname or IP address of the SSH server. (Required)
- port (integer): The port for the SSH service, typically 22. (Required)
- username (string): The username used for authentication to the SSH target. (Optional)
- password (string): The password associated with the provided username. (Optional)
- privateKey (string): The private key for key-based SSH authentication. (Optional)
- passphrase (string): The passphrase for the private key, if applicable. (Optional)
- useExcaliburCredentials (boolean): Whether to use credentials managed by Excalibur. The default is false. (Optional)
- authorizationRequired (boolean): Whether QR-based authorization is required. (Optional)
- tunnelid (integer): The ID of the tunnel to use for the connection. Default is null (no tunnel). (Optional)
- clipboard (object): Clipboard configuration settings. (Required)
  - enableCopy (boolean): Allows copying to the remote session. (Required)
  - enablePaste (boolean): Allows pasting from the remote session to the client. (Required)
- fileTransfer (object): File transfer configuration settings. (Optional)
  - uploadEnabled (boolean): Allows file uploads to the remote session. (Required)
  - downloadEnabled (boolean): Allows file downloads from the remote session. (Required)
  - uploadFileSizeLimit (number): Maximum file size for uploads in bytes. The default is null (no limit). (Optional)
  - rootDirectory (string): Specifies the root directory for file transfers on the remote system. Default is the user's home directory. (Optional)
- recording (object): Session recording settings. (Required)
  - enabled (boolean): Enables recording for the session. The default is false. (Required)
  - retentionPeriod (number): The retention period for session recordings in minutes. null indicates unlimited retention. (Optional)

Example of Request Body with single target:

{
  "name": "Corporate SSH Server",
  "description": "SSH target for secure corporate network access",
  "hostname": "ssh.example.com",
  "port": 22,
  "username": "admin",
  "password": "securePassword123!",
  "useExcaliburCredentials": false,
  "authorizationRequired": true,
  "fileTransfer": {
    "uploadEnabled": true,
    "downloadEnabled": true,
    "uploadFileSizeLimit": 10485760,
    "rootDirectory": "/home/admin/uploads"
  },
  "recording": {
    "enabled": true,
    "retentionPeriod": 4320
  }
}

Example of Request Body with multiple targets:

[
  {
    "name": "Corporate SSH Server",
    "description": "SSH target for secure corporate network access",
    "hostname": "ssh.example.com",
    "port": 22,
    "username": "admin",
    "password": "securePassword123!",
    "useExcaliburCredentials": false,
    "authorizationRequired": true,
    "fileTransfer": {
      "uploadEnabled": true,
      "downloadEnabled": true,
      "uploadFileSizeLimit": 10485760,
      "rootDirectory": "/home/admin/uploads"
    },
    "recording": {
      "enabled": true,
      "retentionPeriod": 4320
    }
  },
  {
    "name": "Corporate SSH Server 2",
    "description": "SSH target for secure corporate network access",
    "hostname": "ssh2.example.com",
    "port": 22,
    "username": "admin2",
    "password": "securePassword123!",
    "useExcaliburCredentials": false,
    "authorizationRequired": false,
    "fileTransfer": {
      "uploadEnabled": false,
      "downloadEnabled": false
    },
    "recording": {
      "enabled": false
    }
  }
]

Response¶

Upon success, the application returns status code 201 Created and in the response body JSON data containing the following parameter:

ids (array of integers): Unique IDs of the newly created PAM targets.

Example of Response Body:

{
  "ids": [
    5678
  ]
}

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X POST {base_url}/api/v1/tenants/my-tenant/pam/targets/ssh \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Corporate SSH Server",
    "description": "SSH target for secure corporate network access",
    "hostname": "ssh.example.com",
    "port": 22,
    "username": "admin",
    "privateKey": "-----BEGIN PRIVATE KEY-----\\nMIIEvQIBADANBgkq...\\n-----END PRIVATE KEY-----",
    "passphrase": "newPassphrase",
    "useExcaliburCredentials": false,
    "authorizationRequired": true,
    "fileTransfer": {
      "uploadEnabled": true,
      "downloadEnabled": true,
      "uploadFileSizeLimit": 10485760,
      "rootDirectory": "/home/admin/uploads"
    },
    "recording": {
      "enabled": true,
      "retentionPeriod": 4320
    }
  }'

Update SSH PAM Target¶

Endpoint PATCH /api/v1/pam/targets/ssh/{id}
Permissions: pam_targets_update

This endpoint allows clients to update the configuration details of an existing SSH PAM target. Administrators can modify various parameters such as hostname, credentials, and file transfer settings. Any changes made will apply to new sessions, while ongoing sessions remain unaffected.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).
Content-Type: application/json Specifies the format of the request payload.

Path Parameters¶

id (integer): The unique identifier of the SSH PAM target to be updated. (Required)

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

Provide the fields you want to update in the request body. Fields not included in the request will remain unchanged.

name (string): The name of the SSH target, used for identification in the system. (Optional)
description (string): An optional description of the SSH target to provide context. (Optional)
hostname (string): The hostname or IP address of the SSH server. (Optional)
port (integer): The port for the SSH service, typically 22. (Optional)
username (string): The username used for authentication to the SSH target. (Optional)
password (string): The password associated with the provided username. (Optional)
privateKey (string): The private key for key-based SSH authentication. (Optional)
passphrase (string): The passphrase for the private key, if applicable. (Optional)
useExcaliburCredentials (boolean): Whether to use credentials managed by Excalibur. The default is false. (Optional)
authorizationRequired (boolean): Whether QR-based authorization is required. (Optional)
tunnelID (integer): The ID of the tunnel to use for the connection. Default is null (no tunnel). (Optional)
clipboard (object): Clipboard configuration settings. (Optional)
- enableCopy (boolean): Allows copying to the remote session. (Optional)
- enablePaste (boolean): Allows pasting from the remote session to the client. (Required)
fileTransfer (object): File transfer configuration settings. (Optional)
- uploadEnabled (boolean): Allows file uploads to the remote session. (Optional)
- downloadEnabled (boolean): Allows file downloads from the remote session. (Optional)
- uploadFileSizeLimit (number): Maximum file size for uploads in bytes. The default is null (no limit). (Optional)
- rootDirectory (string): Specifies the root directory for file transfers on the remote system. Default is the user's home directory. (Optional)
recording (object): Session recording settings. (Optional)
- enabled (boolean): Enables recording for the session. The default is false. (Optional)
- retentionPeriod (number): The retention period for session recordings in minutes. null indicates unlimited retention. (Optional)

Response¶

Upon success, the application returns status code 204 No Content, indicating that the SSH PAM target has been successfully updated.

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X PATCH {base_url}/api/v1/pam/targets/ssh/5678 \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Corporate SSH Server Updated",
    "hostname": "updated-ssh.example.com",
    "username": "newAdmin",
    "privateKey": "-----BEGIN PRIVATE KEY-----\\nMIIEvQIBADANBgkq...\\n-----END PRIVATE KEY-----",
    "passphrase": "newPassphrase",
    "fileTransfer": {
      "uploadEnabled": true,
      "downloadEnabled": false
    },
    "recording": {
      "enabled": true,
      "retentionPeriod": 1440
    }
  }'

Update SSH PAM Target in Tenant¶

Endpoint PATCH /api/v1/tenants/{tenantIdOrSlug}/pam/targets/ssh/{id}
Permissions: pam_targets_update

This endpoint allows clients to update the configuration details of an existing SSH PAM target. Administrators can modify various parameters such as hostname, credentials, and file transfer settings. Any changes made will apply to new sessions, while ongoing sessions remain unaffected.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).
Content-Type: application/json Specifies the format of the request payload.

Path Parameters¶

tenantIdOrSlug (string or integer): The unique identifier or slug of the tenant.
id (integer): The unique identifier of the SSH PAM target to be updated. (Required)

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

Provide the fields you want to update in the request body. Fields not included in the request will remain unchanged.

name (string): The name of the SSH target, used for identification in the system. (Optional)
description (string): An optional description of the SSH target to provide context. (Optional)
hostname (string): The hostname or IP address of the SSH server. (Optional)
port (integer): The port for the SSH service, typically 22. (Optional)
username (string): The username used for authentication to the SSH target. (Optional)
password (string): The password associated with the provided username. (Optional)
privateKey (string): The private key for key-based SSH authentication. (Optional)
passphrase (string): The passphrase for the private key, if applicable. (Optional)
useExcaliburCredentials (boolean): Whether to use credentials managed by Excalibur. The default is false. (Optional)
authorizationRequired (boolean): Whether QR-based authorization is required. (Optional)
tunnelID (integer): The ID of the tunnel to use for the connection. Default is null (no tunnel). (Optional)
clipboard (object): Clipboard configuration settings. (Optional)
- enableCopy (boolean): Allows copying to the remote session. (Optional)
- enablePaste (boolean): Allows pasting from the remote session to the client. (Required)
fileTransfer (object): File transfer configuration settings. (Optional)
- uploadEnabled (boolean): Allows file uploads to the remote session. (Optional)
- downloadEnabled (boolean): Allows file downloads from the remote session. (Optional)
- uploadFileSizeLimit (number): Maximum file size for uploads in bytes. The default is null (no limit). (Optional)
- rootDirectory (string): Specifies the root directory for file transfers on the remote system. Default is the user's home directory. (Optional)
recording (object): Session recording settings. (Optional)
- enabled (boolean): Enables recording for the session. The default is false. (Optional)
- retentionPeriod (number): The retention period for session recordings in minutes. null indicates unlimited retention. (Optional)

Response¶

Upon success, the application returns status code 204 No Content, indicating that the SSH PAM target has been successfully updated.

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X PATCH {base_url}/api/v1/tenants/my-tenant/pam/targets/ssh/5678 \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Corporate SSH Server Updated",
    "hostname": "updated-ssh.example.com",
    "username": "newAdmin",
    "privateKey": "-----BEGIN PRIVATE KEY-----\\nMIIEvQIBADANBgkq...\\n-----END PRIVATE KEY-----",
    "passphrase": "newPassphrase",
    "fileTransfer": {
      "uploadEnabled": true,
      "downloadEnabled": false
    },
    "recording": {
      "enabled": true,
      "retentionPeriod": 1440
    }
  }'

Add VNC PAM Target¶

Endpoint POST /api/v1/pam/targets/vnc
Permissions: pam_targets_create

This endpoint enables clients to securely add a new Virtual Network Computing (VNC) PAM target to the system. The VNC target can be configured with advanced settings like session recording to ensure security and usability.

Upon successful creation, the VNC target is available for secure session initiation through the Excalibur dashboard interface after successful user authentication.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).
Content-Type: application/json Specifies the format of the request payload.

Path Parameters¶

N/A: This endpoint does not utilize path parameters.

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

(object or array):
- name (string): The name of the VNC target, used for identification in the system. (Required)
- description (string): An optional description of the VNC target to provide context. (Optional)
- hostname (string): The hostname or IP address of the VNC server. (Required)
- port (integer): The port for the VNC service, typically 5900. (Required)
- username (string): The username used for authentication to the VNC target. (Optional)
- password (string): The password associated with the provided username. (Optional)
- useExcaliburCredentials (boolean): Whether to use credentials managed by Excalibur. The default is false. (Optional)
- authorizationRequired (boolean): Whether QR-based authorization is required. (Optional)
- tunnelid (integer): The ID of the tunnel to use for the connection. Default is null (no tunnel). (Optional)
- clipboard (object): Clipboard configuration settings. (Required)
  - enableCopy (boolean): Allows copying to the remote session. (Required)
  - enablePaste (boolean): Allows pasting from the remote session to the client. (Required)
- recording (object): Session recording settings. (Required)
  - enabled (boolean): Enables recording for the session. The default is false. (Required)
  - retentionPeriod (number): The retention period for session recordings in minutes. null indicates unlimited retention. (Optional)

Example of Request Body with single target:

{
  "name": "Corporate VNC Server",
  "description": "VNC target for secure corporate network access",
  "hostname": "ssh.example.com",
  "port": 22,
  "username": "admin",
  "password": "securePassword123!",
  "useExcaliburCredentials": false,
  "authorizationRequired": true,
  "clipboard": {
    "enableCopy": true,
    "enablePaste": true
  },
  "recording": {
    "enabled": true,
    "retentionPeriod": 4320
  }
}

Example of Request Body with multiple targets:

[
  {
    "name": "Corporate VNC Server",
    "description": "VNC target for secure corporate network access",
    "hostname": "ssh.example.com",
    "port": 22,
    "username": "admin",
    "password": "securePassword123!",
    "useExcaliburCredentials": false,
    "authorizationRequired": true,
    "clipboard": {
      "enableCopy": true,
      "enablePaste": true
    },
    "recording": {
      "enabled": true,
      "retentionPeriod": 4320
    }
  },
  {
    "name": "Corporate VNC Server 2",
    "description": "VNC target for secure corporate network access",
    "hostname": "ssh2.example.com",
    "port": 22,
    "username": "admin2",
    "password": "securePassword123!",
    "useExcaliburCredentials": false,
    "authorizationRequired": false,
    "clipboard": {
      "enableCopy": false,
      "enablePaste": false
    },
    "recording": {
      "enabled": false
    }
  }
]

Response¶

Upon success, the application returns status code 201 Created and in the response body JSON data containing the following parameter:

ids (array of integers): Unique IDs of the newly created PAM targets.

Example of Response Body:

{
  "ids": [
    5678
  ]
}

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X POST {base_url}/api/v1/pam/targets/vnc \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Corporate VNC Server",
    "description": "VNC target for secure corporate network access",
    "hostname": "vnc.example.com",
    "port": 5900,
    "username": "admin",
    "password": "securePassword123!",
    "useExcaliburCredentials": false,
    "authorizationRequired": true,
    "clibpard": {
      "enableCopy": true,
      "enablePaste": true
    },
    "recording": {
      "enabled": true,
      "retentionPeriod": 4320
    }
  }'

Add VNC PAM Target to Tenant¶

Endpoint POST /api/v1/tenants/{tenantIdOrSlug}/pam/targets/vnc
Permissions: pam_targets_create

This endpoint enables clients to securely add a new Virtual Network Computing (VNC) PAM target to the system. The VNC target can be configured with advanced settings like session recording to ensure security and usability.

Upon successful creation, the VNC target is available for secure session initiation through the Excalibur dashboard interface after successful user authentication.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).
Content-Type: application/json Specifies the format of the request payload.

Path Parameters¶

tenantIdOrSlug (string or integer): The unique identifier or slug of the tenant.

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

(object or array):
- name (string): The name of the VNC target, used for identification in the system. (Required)
- description (string): An optional description of the VNC target to provide context. (Optional)
- hostname (string): The hostname or IP address of the VNC server. (Required)
- port (integer): The port for the VNC service, typically 5900. (Required)
- username (string): The username used for authentication to the VNC target. (Optional)
- password (string): The password associated with the provided username. (Optional)
- useExcaliburCredentials (boolean): Whether to use credentials managed by Excalibur. The default is false. (Optional)
- authorizationRequired (boolean): Whether QR-based authorization is required. (Optional)
- tunnelid (integer): The ID of the tunnel to use for the connection. Default is null (no tunnel). (Optional)
- clipboard (object): Clipboard configuration settings. (Required)
  - enableCopy (boolean): Allows copying to the remote session. (Required)
  - enablePaste (boolean): Allows pasting from the remote session to the client. (Required)
- recording (object): Session recording settings. (Required)
  - enabled (boolean): Enables recording for the session. The default is false. (Required)
  - retentionPeriod (number): The retention period for session recordings in minutes. null indicates unlimited retention. (Optional)

Example of Request Body with single target:

{
  "name": "Corporate VNC Server",
  "description": "VNC target for secure corporate network access",
  "hostname": "ssh.example.com",
  "port": 22,
  "username": "admin",
  "password": "securePassword123!",
  "useExcaliburCredentials": false,
  "authorizationRequired": true,
  "clipboard": {
    "enableCopy": true,
    "enablePaste": true
  },
  "recording": {
    "enabled": true,
    "retentionPeriod": 4320
  }
}

Example of Request Body with multiple targets:

[
  {
    "name": "Corporate VNC Server",
    "description": "VNC target for secure corporate network access",
    "hostname": "ssh.example.com",
    "port": 22,
    "username": "admin",
    "password": "securePassword123!",
    "useExcaliburCredentials": false,
    "authorizationRequired": true,
    "clipboard": {
      "enableCopy": true,
      "enablePaste": true
    },
    "recording": {
      "enabled": true,
      "retentionPeriod": 4320
    }
  }
]

Response¶

Upon success, the application returns status code 201 Created and in the response body JSON data containing the following parameter:

ids (array of integers): Unique IDs of the newly created PAM targets.

Example of Response Body:

{
  "ids": [
    5678
  ]
}

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X POST {base_url}/api/v1/tenants/my-tenant/pam/targets/vnc \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Corporate VNC Server",
    "description": "VNC target for secure corporate network access",
    "hostname": "vnc.example.com",
    "port": 5900,
    "username": "admin",
    "password": "securePassword123!",
    "useExcaliburCredentials": false,
    "authorizationRequired": true,
    "clibpard": {
      "enableCopy": true,
      "enablePaste": true
    },
    "recording": {
      "enabled": true,
      "retentionPeriod": 4320
    }
  }'

Update VNC PAM Target¶

Endpoint PATCH /api/v1/pam/targets/vnc/{id}
Permissions: pam_targets_update

This endpoint allows clients to update the configuration details of an existing VNC PAM target. Administrators can modify various parameters such as hostname and credentials. Any changes made will apply to new sessions, while ongoing sessions remain unaffected.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).
Content-Type: application/json Specifies the format of the request payload.

Path Parameters¶

id (integer): The unique identifier of the VNC PAM target to be updated. (Required)

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

Provide the fields you want to update in the request body. Fields not included in the request will remain unchanged.

name (string): The name of the VNC target, used for identification in the system. (Optional)
description (string): An optional description of the VNC target to provide context. (Optional)
hostname (string): The hostname or IP address of the VNC server. (Optional)
port (integer): The port for the VNC service, typically 5900. (Optional)
username (string): The username used for authentication to the VNC target. (Optional)
password (string): The password associated with the provided username. (Optional)
useExcaliburCredentials (boolean): Whether to use credentials managed by Excalibur. The default is false. (Optional)
authorizationRequired (boolean): Whether QR-based authorization is required. (Optional)
tunnelid (integer): The ID of the tunnel to use for the connection. Default is null (no tunnel). (Optional)
clipboard (object): Clipboard configuration settings. (Optional)
- enableCopy (boolean): Allows copying to the remote session. (Optional)
- enablePaste (boolean): Allows pasting from the remote session to the client. (Optional)
recording (object): Session recording settings. (Optional)
- enabled (boolean): Enables recording for the session. The default is false. (Optional)
- retentionPeriod (number): The retention period for session recordings in minutes. null indicates unlimited retention. (Optional)

Response¶

Upon success, the application returns status code 204 No Content, indicating that the VNC PAM target has been successfully updated.

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X PATCH {base_url}/api/v1/pam/targets/vnc/5678 \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Corporate VNC Server",
    "description": "VNC target for secure corporate network access",
    "hostname": "vnc.example.com",
    "port": 5900,
    "username": "admin",
    "password": "securePassword123!",
    "useExcaliburCredentials": false,
    "authorizationRequired": true,
    "clibpard": {
      "enableCopy": true,
      "enablePaste": true
    },
    "recording": {
      "enabled": true,
      "retentionPeriod": 4320
    }
  }'

Update VNC PAM Target in Tenant¶

Endpoint PATCH /api/v1/tenants/{tenantIdOrSlug}/pam/targets/vnc/{id}
Permissions: pam_targets_update

This endpoint allows clients to update the configuration details of an existing VNC PAM target. Administrators can modify various parameters such as hostname, and credentials. Any changes made will apply to new sessions, while ongoing sessions remain unaffected.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).
Content-Type: application/json Specifies the format of the request payload.

Path Parameters¶

tenantIdOrSlug (string or integer): The unique identifier or slug of the tenant.
id (integer): The unique identifier of the VNC PAM target to be updated. (Required)

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

Provide the fields you want to update in the request body. Fields not included in the request will remain unchanged.

name (string): The name of the VNC target, used for identification in the system. (Optional)
description (string): An optional description of the VNC target to provide context. (Optional)
hostname (string): The hostname or IP address of the VNC server. (Optional)
port (integer): The port for the VNC service, typically 5900. (Optional)
username (string): The username used for authentication to the VNC target. (Optional)
password (string): The password associated with the provided username. (Optional)
useExcaliburCredentials (boolean): Whether to use credentials managed by Excalibur. The default is false. (Optional)
authorizationRequired (boolean): Whether QR-based authorization is required. (Optional)
tunnelid (integer): The ID of the tunnel to use for the connection. Default is null (no tunnel). (Optional)
clipboard (object): Clipboard configuration settings. (Optional)
- enableCopy (boolean): Allows copying to the remote session. (Optional)
- enablePaste (boolean): Allows pasting from the remote session to the client. (Optional)
recording (object): Session recording settings. (Optional)
- enabled (boolean): Enables recording for the session. The default is false. (Optional)
- retentionPeriod (number): The retention period for session recordings in minutes. null indicates unlimited retention. (Optional)

Response¶

Upon success, the application returns status code 204 No Content, indicating that the VNC PAM target has been successfully updated.

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X PATCH {base_url}/api/v1/tenants/my-tenant/pam/targets/vnc/5678 \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Corporate VNC Server",
    "description": "VNC target for secure corporate network access",
    "hostname": "vnc.example.com",
    "port": 5900,
    "username": "admin",
    "password": "securePassword123!",
    "useExcaliburCredentials": false,
    "authorizationRequired": true,
    "clibpard": {
      "enableCopy": true,
      "enablePaste": true
    },
    "recording": {
      "enabled": true,
      "retentionPeriod": 4320
    }
  }'

Add Web PAM Target¶

Endpoint POST /api/v1/pam/targets/vitro
Permissions: pam_targets_create

This endpoint enables clients to securely add a new Web PAM target to the system. The Web target can be configured with advanced settings like authorization to ensure security and usability.

Upon successful creation, the Web target is available for secure session initiation through the Excalibur dashboard interface after successful user authentication.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).
Content-Type: application/json Specifies the format of the request payload.

Path Parameters¶

N/A: This endpoint does not utilize path parameters.

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

(object or array):
- name (string): The name of the Web target, used for identification in the system. (Required)
- description (string): An optional description of the Web target to provide context. (Optional)
- url (string): The address of the website. (Required)
- inactivityTimeout (number): The inactivity timeout in seconds. The session is closed after specified inactivity timeout. (Required)
- authorizationRequired (boolean): Whether QR-based authorization is required. (Required)

Example of Request Body with single target:

{
  "name": "Corporate Web Server",
  "description": "Web target for secure corporate network access",
  "url": "https://web.example.com",
  "inactivityTimeout": 180,
  "authorizationRequired": true
}

Example of Request Body with multiple targets:

[
  {
    "name": "Corporate Web Server",
    "description": "Web target for secure corporate network access",
    "url": "https://web.example.com",
    "inactivityTimeout": 180,
    "authorizationRequired": true
  },
  {
    "name": "Corporate Web Server 2",
    "description": "Web target for secure corporate network access",
    "url": "https://web2.example.com",
    "inactivityTimeout": 360,
    "authorizationRequired": false
  }
]

Response¶

Upon success, the application returns status code 201 Created and in the response body JSON data containing the following parameter:

ids (array of integers): Unique IDs of the newly created PAM targets.

Example of Response Body:

{
  "ids": [
    5678
  ]
}

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X POST {base_url}/api/v1/pam/targets/vitro \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Corporate Web Server",
    "description": "Web target for secure corporate network access",
    "url": "https://web.example.com",
    "inactivityTimeout": 180,
    "authorizationRequired": true
  }'

Add Web PAM Target to Tenant¶

Endpoint POST /api/v1/tenants/{tenantIdOrSlug}/pam/targets/vitro
Permissions: pam_targets_create

This endpoint enables clients to securely add a new Web PAM target to the system. The Web target can be configured with advanced settings like authorization to ensure security and usability.

Upon successful creation, the Web target is available for secure session initiation through the Excalibur dashboard interface after successful user authentication.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).
Content-Type: application/json Specifies the format of the request payload.

Path Parameters¶

tenantIdOrSlug (string or integer): The unique identifier or slug of the tenant.

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

(object or array):
- name (string): The name of the Web target, used for identification in the system. (Required)
- description (string): An optional description of the Web target to provide context. (Optional)
- url (string): The address of the website. (Required)
- inactivityTimeout (number): The inactivity timeout in seconds. The session is closed after specified inactivity timeout. (Required)
- authorizationRequired (boolean): Whether QR-based authorization is required. (Required)

Example of Request Body with single target:

{
  "name": "Corporate Web Server",
  "description": "Web target for secure corporate network access",
  "url": "https://web.example.com",
  "inactivityTimeout": 180,
  "authorizationRequired": true
}

Example of Request Body with multiple targets:

[
  {
    "name": "Corporate Web Server",
    "description": "Web target for secure corporate network access",
    "url": "https://web.example.com",
    "inactivityTimeout": 180,
    "authorizationRequired": true
  },
  {
    "name": "Corporate Web Server 2",
    "description": "Web target for secure corporate network access",
    "url": "https://web2.example.com",
    "inactivityTimeout": 360,
    "authorizationRequired": false
  }
]

Response¶

Upon success, the application returns status code 201 Created and in the response body JSON data containing the following parameter:

ids (array of integers): Unique IDs of the newly created PAM targets.

Example of Response Body:

{
  "ids": [
    5678
  ]
}

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X POST {base_url}/api/v1/tenants/my-tenant/pam/targets/vitro \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Corporate Web Server",
    "description": "Web target for secure corporate network access",
    "url": "https://web.example.com",
    "inactivityTimeout": 180,
    "authorizationRequired": true
  }'

Update Web PAM Target¶

Endpoint PATCH /api/v1/pam/targets/vitro/{id}
Permissions: pam_targets_update

This endpoint allows clients to update the configuration details of an existing Web PAM target. Administrators can modify various parameters such as hostname and credentials. Any changes made will apply to new sessions, while ongoing sessions remain unaffected.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).
Content-Type: application/json Specifies the format of the request payload.

Path Parameters¶

id (integer): The unique identifier of the VNC PAM target to be updated. (Required)

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

Provide the fields you want to update in the request body. Fields not included in the request will remain unchanged.

name (string): The name of the Web target, used for identification in the system. (Optional)
description (string): An optional description of the Web target to provide context. (Optional)
url (string): The address of the website. (Optional)
inactivityTimeout (number): The inactivity timeout in seconds. The session is closed after specified inactivity timeout. (Optional)
authorizationRequired (boolean): Whether QR-based authorization is required. (Optional)

Response¶

Upon success, the application returns status code 204 No Content, indicating that the Web PAM target has been successfully updated.

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X PATCH {base_url}/api/v1/pam/targets/vitro/5678 \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Corporate Web Server",
    "description": "Web target for secure corporate network access",
    "url": "https://web.example.com",
    "inactivityTimeout": 180,
    "authorizationRequired": true
  }'

Update Web PAM Target in Tenant¶

Endpoint PATCH /api/v1/tenants/{tenantIdOrSlug}/pam/targets/vitro/{id}
Permissions: pam_targets_update

This endpoint allows clients to update the configuration details of an existing Web PAM target. Administrators can modify various parameters such as hostname, and credentials. Any changes made will apply to new sessions, while ongoing sessions remain unaffected.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).
Content-Type: application/json Specifies the format of the request payload.

Path Parameters¶

tenantIdOrSlug (string or integer): The unique identifier or slug of the tenant.
id (integer): The unique identifier of the VNC PAM target to be updated. (Required)

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

Provide the fields you want to update in the request body. Fields not included in the request will remain unchanged.

name (string): The name of the Web target, used for identification in the system. (Optional)
description (string): An optional description of the Web target to provide context. (Optional)
url (string): The address of the website. (Optional)
inactivityTimeout (number): The inactivity timeout in seconds. The session is closed after specified inactivity timeout. (Optional)
authorizationRequired (boolean): Whether QR-based authorization is required. (Optional)

Response¶

Upon success, the application returns status code 204 No Content, indicating that the Web PAM target has been successfully updated.

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X PATCH {base_url}/api/v1/tenants/my-tenant/pam/targets/vitro/5678 \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Corporate Web Server",
    "description": "Web target for secure corporate network access",
    "url": "https://web.example.com",
    "inactivityTimeout": 180,
    "authorizationRequired": true
  }'

Get List of PAM Targets¶

Endpoint GET /api/v1/pam/targets
Permissions: pam_targets_read_all or pam_targets_read_own

This endpoint allows clients to retrieve a list of PAM targets (RDP, SSH, VNC or Web) configured in the system. The response includes details for each PAM target, such as configuration, access policies, and metadata, enabling administrators to review or manage multiple targets efficiently.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

N/A: This endpoint does not utilize path parameters.

Query Parameters¶

This endpoint supports filtering, pagination and sorting as described in Excalibur v4 API Query Parameters section.

Request Body¶

N/A: This endpoint does not support request body

Response¶

Upon success, the application returns status code 200 OK and in the response body JSON data containing a paginated list of PAM targets with their total count.

total (integer): The total number of PAM targets available in the system.
entities (array): A list of PAM targets, each with the following parameters:
- id (integer): The unique identifier of the PAM target. (Required)
- name (string): The name of the PAM target, used for identification in the system. (Required)
- description (string): An optional description of the PAM target to provide context. (Optional)
- hostname (string): The hostname or IP address of the PAM target. (Optional)
- port (integer): The port for the service, typically 22 for SSH, 3389 for RDP and 5900 for VNC. (Optional)
- type (string): The type of the PAM target. Can be either “RDP”, “SSH”, “VNC” or “Web”. (Required)
- password (string): The password associated with the provided username. (Optional)
- tenantid (integer): The unique identifier of the tenant. (Optional)

Example of response body:

{
  "total": 123,
  "entities": [
    {
      "id": 1234,
      "name": "Corporate SSH Server",
      "description": "SSH target for secure corporate network access",
      "hostname": "ssh.example.com",
      "port": 22,
      "type": "SSH"
    },
    {
      "id": 2345,
      "name": "Corporate RDP Server",
      "description": "RDP target for secure corporate network access",
      "hostname": "rdp.example.com",
      "port": 3389,
      "type": "RDP"
    },
    {
      "id": 3456,
      "name": "Corporate VNC Server",
      "description": "VNC target for secure corporate network access",
      "hostname": "vnc.example.com",
      "port": 5900,
      "type": "VNC"
    },
    {
      "id": 4567,
      "name": "Corporate Web Server",
      "description": "Web target for secure corporate network access",
      "type": "Web"
    }
  ]
}

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X GET {base_url}/api/v1/pam/targets \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json"

Get List of PAM Targets in Tenant¶

Endpoint GET /api/v1/tenants/{tenantIdOrSlug}/pam/targets
Permissions: pam_targets_read_all or pam_targets_read_own

This endpoint allows clients to retrieve a list of PAM targets (RDP, SSH, VNC or Web) configured in the system. The response includes details for each PAM target, such as configuration, access policies, and metadata, enabling administrators to review or manage multiple targets efficiently.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

tenantIdOrSlug (string or integer): The unique identifier or slug of the tenant.

Query Parameters¶

This endpoint supports filtering, pagination and sorting as described in Excalibur v4 API Query Parameters section.

Request Body¶

N/A: This endpoint does not support request body

Response¶

Upon success, the application returns status code 200 OK and in the response body JSON data containing a paginated list of PAM targets with their total count.

total (integer): The total number of PAM targets available in the system.
entities (array): A list of PAM targets, each with the following parameters:
- id (integer): The unique identifier of the PAM target.
- name (string): The name of the PAM target, used for identification in the system. (Required)
- description (string): An optional description of the PAM target to provide context. (Optional)
- hostname (string): The hostname or IP address of the PAM target. (Optional)
- port (integer): The port for the service, typically 22 for SSH, 3389 for RDP and 5900 for VNC. (Optional)
- type (string): The type of the PAM target. Can be either “RDP”, “SSH”, “VNC” or “Web”. (Required)
- tenantid (integer): The unique identifier of the tenant. (Optional)

Example of response body:

{
  "total": 123,
  "entities": [
    {
      "id": 1234,
      "name": "Corporate SSH Server",
      "description": "SSH target for secure corporate network access",
      "hostname": "ssh.example.com",
      "port": 22,
      "type": "SSH"
    },
    {
      "id": 2345,
      "name": "Corporate RDP Server",
      "description": "RDP target for secure corporate network access",
      "hostname": "rdp.example.com",
      "port": 3389,
      "type": "RDP"
    },
    {
      "id": 3456,
      "name": "Corporate VNC Server",
      "description": "VNC target for secure corporate network access",
      "hostname": "vnc.example.com",
      "port": 5900,
      "type": "VNC"
    },
    {
      "id": 4567,
      "name": "Corporate Web Server",
      "description": "Web target for secure corporate network access",
      "type": "Web"
    }
  ]
}

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X GET {base_url}/api/v1/tenants/my-tenant/pam/targets \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json"

Delete PAM Target¶

Endpoint DELETE /api/v1/pam/targets/{id}
Permissions: pam_targets_delete

This endpoint allows clients to delete a specific PAM target (RDP, SSH, VNC or Web) from the system. Once deleted, the PAM target will no longer be accessible. However, sessions initiated with the target prior to deletion remain untouched for auditing purposes. The deleted PAM target can still be accessed via the audit view for historical and compliance records.

Use this endpoint with caution, as the action is irreversible.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

id (integer): The unique identifier of the PAM target to be deleted. (Required)

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

N/A: This endpoint does not support request body

Response¶

Upon success, the application returns status code 204 No Content, indicating that the PAM target has been successfully deleted.

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X DELETE {base_url}/api/v1/pam/targets/5678 \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json"

Delete PAM Target in Tenant¶

Endpoint DELETE /api/v1/tenants/{tenantIdOrSlug}/pam/targets/{id}
Permissions: pam_targets_delete

This endpoint allows clients to delete a specific PAM target (RDP, SSH, VNC or Web) from the system. Once deleted, the target will no longer be accessible. However, sessions initiated with the target prior to deletion remain untouched for auditing purposes. The deleted PAM target can still be accessed via the audit view for historical and compliance records.

Use this endpoint with caution, as the action is irreversible.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

tenantIdOrSlug (string or integer): The unique identifier or slug of the tenant.
id (integer): The unique identifier of the PAM target to be deleted. (Required)

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

N/A: This endpoint does not support request body

Response¶

Upon success, the application returns status code 204 No Content, indicating that the PAM target has been successfully deleted.

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X DELETE {base_url}/api/v1/tenants/my-tenant/pam/targets/5678 \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json"

Delete Multiple PAM Targets¶

Endpoint DELETE /api/v1/pam/targets
Permissions: pam_targets_delete

This endpoint allows clients to delete multiple PAM targets (RDP, SSH, VNC or Web) from the system in a single request. The targets to be deleted are specified by their unique IDs (does not matter what type PAM target is, in Excalibur every PAM target has its unique ID), passed in ids parameter using brackets in the query string.

Once deleted, the targets will no longer be accessible, but historical session records will remain available for auditing purposes.

Use this endpoint with caution, as the action is irreversible.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

N/A: This endpoint does not utilize path parameters.

Query Parameters¶

ids (array of integers): The unique identifiers of the PAM targets to be deleted. This parameter is repeatable for each target to be deleted. (Required)

Request Body¶

N/A: This endpoint does not support request body

Response¶

Upon success, the application returns status code 204 No Content.

If no IDs are provided, a 422 Unprocessable Entity error is returned.

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X DELETE {base_url}/api/v1/pam/targets?ids[]=1234&ids[]=5678&ids[]=91011 \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json"

Delete Multiple PAM Targets in Tenant¶

Endpoint DELETE /api/v1/tenants/{tenantIdOrSlug}/pam/targets
Permissions: pam_targets_delete

This endpoint allows clients to delete multiple PAM targets (RDP, SSH, VNC or Web) from the system in a single request. The targets to be deleted are specified by their unique IDs (does not matter what type PAM target is, in Excalibur every PAM target has its unique ID), passed in ids parameter using brackets in the query string.

Once deleted, the targets will no longer be accessible, but historical session records will remain available for auditing purposes.

Use this endpoint with caution, as the action is irreversible.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

tenantIdOrSlug (string or integer): The unique identifier or slug of the tenant.

Query Parameters¶

ids (array of integers): The unique identifiers of the PAM targets to be deleted. This parameter is repeatable for each target to be deleted. (Required)

Request Body¶

N/A: This endpoint does not support request body

Response¶

Upon success, the application returns status code 204 No Content.

If no IDs are provided, a 422 Unprocessable Entity error is returned.

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X DELETE {base_url}/api/v1/tenants/my-tenant/pam/targets?ids[]=1234&ids[]=5678&ids[]=91011 \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json"

Get List of PAM Groups¶

Endpoint GET /api/v1/pamGroups
Permissions: pam_groups_read

This endpoint allows clients to retrieve a list of PAM groups configured in the system.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

N/A: This endpoint does not utilize path parameters.

Query Parameters¶

This endpoint supports filtering, pagination and sorting as described in Excalibur v4 API Query Parameters section.

Request Body¶

N/A: This endpoint does not support request body

Response¶

Upon success, the application returns status code 200 OK and in the response body JSON data containing a paginated list of PAM groups with their total count.

total (integer): The total number of PAM targets available in the system.
entities (array): A list of PAM targets, each with the following parameters:
- id (integer): The unique identifier of the PAM target.
- name (string): The name of the PAM target, used for identification in the system.
- description (string, optional): An optional description of the PAM target to provide context.
- isBuiltIn (boolean): Indicates whether this group is the builtin PAM group or a custom group created later.
- borderColor (string, optional): The group’s marker border color, which shows up in the UI dashboard. Used to easily differentiate between multiple groups.
- bgColor (string, optional): The group’s marker background color, which shows up in the UI dashboard. Used to easily differentiate between multiple groups.
- textColor (string, optional): The group’s marker text color, which shows up in the UI dashboard. Used to easily differentiate between multiple groups.

Example of response body:

{
  "total": 2,
  "entities": [
    {
      "id": 1,
      "name": "Default system PAM Target Group",
      "isBuiltIn": true,
      "description": "This is the default system PAM target group",
      "textColor": "#000000"
    },
    {
      "id": 2,
      "name": "Custom PAM Target Group",
      "isBuiltIn": false,
      "description": "Custom description",
      "textColor": "#000000"
    }
  ]
}

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X GET {base_url}/api/v1/pamGroups \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json"

Get List of PAM Groups in Tenant¶

Endpoint GET /api/v1/tenants/{tenantIdOrSlug}/pamGroups
Permissions: pam_groups_read

This endpoint allows clients to retrieve a list of PAM groups configured in the Excalibur system in a specific tenant.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

tenantIdOrSlug (string or integer): The unique identifier or slug of the tenant.

Query Parameters¶

This endpoint supports filtering, pagination and sorting as described in Excalibur v4 API Query Parameters section.

Request Body¶

N/A: This endpoint does not support request body

Response¶

Upon success, the application returns status code 200 OK and in the response body JSON data containing a paginated list of PAM groups with their total count.

total (integer): The total number of PAM targets available in the system.
entities (array): A list of PAM targets, each with the following parameters:
- id (integer): The unique identifier of the PAM target.
- name (string): The name of the PAM target, used for identification in the system.
- description (string, optional): An optional description of the PAM target to provide context.
- isBuiltIn (boolean): Indicates whether this group is the builtin PAM group or a custom group created later.
- borderColor (string, optional): The group’s marker border color, which shows up in the UI dashboard. Used to easily differentiate between multiple groups.
- bgColor (string, optional): The group’s marker background color, which shows up in the UI dashboard. Used to easily differentiate between multiple groups.
- textColor (string, optional): The group’s marker text color, which shows up in the UI dashboard. Used to easily differentiate between multiple groups.

Example of response body:

{
  "total": 2,
  "entities": [
    {
      "id": 1001,
      "name": "Default PAM Target Group",
      "isBuiltIn": true,
      "description": "This is the default PAM Target Group",
      "textColor": "#000000"
    },
    {
      "id": 1002,
      "name": "Custom PAM Target Group",
      "isBuiltIn": false,
      "description": "Custom description",
      "textColor": "#000000"
    }
  ]
}

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X GET {base_url}/api/v1/tenants/my-tenant/pamGroups \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json"

Add PAM Targets to PAM Group¶

Endpoint POST /api/v1/pamGroups/{id}/targets
Permissions: pam_groups_update

This endpoint allows clients to add multiple PAM Targets to a PAM group.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

id (integer): The unique identifier of the PAM group where to assign PAM targets to. (Required)

Query Parameters¶

targetIDs (array of integers): The unique identifiers of the PAM targets to assign.

Request Body¶

N/A: This endpoint does not support request body

Response¶

Upon success, the application returns status code 201 Created with no response body.

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X POST \{base_url}/api/v1/pamGroups/{id}/targets?targetIDs[]=123&targetIDs[]=456 \
  -H "Authorization: Bearer {access_token}"

Add PAM Targets to PAM Group in Tenant¶

Endpoint POST /api/v1/tenants/{tenantIdOrSlug}/pamGroups/{id}/targets
Permissions: pam_groups_update

This endpoint allows clients to add multiple PAM Targets to a PAM group in Tenant.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

id (integer): The unique identifier of the PAM group where to assign PAM targets to. (Required)

Query Parameters¶

targetIDs (array of integers): The unique identifiers of the PAM targets to assign.

Request Body¶

N/A: This endpoint does not support request body

Response¶

Upon success, the application returns status code 201 Created with no response body.

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X POST \{base_url}/api/v1/tenants/my-tenant/pamGroups/{id}/targets?targetIDs[]=123&targetIDs[]=456 \
  -H "Authorization: Bearer {access_token}"

Remove PAM Target from PAM Group¶

Endpoint DELETE /api/v1/pamGroups/{id}/targets/{targetId}
Permissions: pam_groups_update

This endpoint allows clients to remove a single PAM Target from a PAM group in the Excalibur system.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

id (integer): The unique identifier of the PAM group where to assign PAM targets to. (Required)
targetId (integer): The unique identifier of the PAM target to remove from PAM group. (Required)

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

N/A: This endpoint does not support request body

Response¶

Upon success, the application returns status code 204 No Content with no response body.

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X DELETE \{base_url}/api/v1/pamGroups/{id}/targets/123 \
  -H "Authorization: Bearer {access_token}"

Remove PAM Target from PAM Group in Tenant¶

Endpoint DELETE /api/v1/tenants/{tenantIdOrSlug}/pamGroups/{id}/targets/{targetId}
Permissions: pam_groups_update

This endpoint allows clients to remove a single PAM Target from a PAM group in the Excalibur system in a specified tenant.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

id (integer): The unique identifier of the PAM group where to assign PAM targets to. (Required)
targetId (integer): The unique identifier of the PAM target to remove from PAM group. (Required)

Query Parameters¶

N/A: This endpoint does not utilize query parameters.

Request Body¶

N/A: This endpoint does not support request body

Response¶

Upon success, the application returns status code 204 No Content with no response body.

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X DELETE \
  {base_url}/api/v1/tenants/my-tenant/pamGroups/{id}/targets/123 \
  -H "Authorization: Bearer {access_token}"

Remove PAM Targets from PAM Group¶

Endpoint DELETE /api/v1/pamGroups/{id}/targets
Permissions: pam_groups_update

This endpoint allows clients to remove multiple PAM Targets from a PAM group in the Excalibur system.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

id (integer): The unique identifier of the PAM group where to assign PAM targets to. (Required)

Query Parameters¶

targetIDs (array of integers): The unique identifiers of the PAM targets to assign.

Request Body¶

N/A: This endpoint does not support request body

Response¶

Upon success, the application returns status code 204 No Content with no response body.

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X DELETE \{base_url}/api/v1/pamGroups/{id}/targets?targetIDs[]=123&targetIDs[]=456 \
  -H "Authorization: Bearer {access_token}"

Remove PAM Targets from PAM Group in Tenant¶

Endpoint DELETE /api/v1/tenants/{tenantIdOrSlug}/pamGroups/{id}/targets
Permissions: pam_groups_update

This endpoint allows clients to remove multiple PAM Targets from a PAM group in the Excalibur system in a specified tenant.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

id (integer): The unique identifier of the PAM group where to assign PAM targets to. (Required)

Query Parameters¶

targetIDs (array of integers): The unique identifiers of the PAM targets to assign.

Request Body¶

N/A: This endpoint does not support request body

Response¶

Upon success, the application returns status code 204 No Content with no response body.

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X DELETE \
  {base_url}/api/v1/tenants/my-tenant/pamGroups/{id}/targets?targetIDs[]=123&targetIDs[]=456 \
  -H "Authorization: Bearer {access_token}"

Get List of PAM Targets in PAM Group¶

Endpoint GET /api/v1/pamGroups/{id}/targets
Permissions: pam_groups_read and pam_targets_read_all

This endpoint allows clients to retrieve a list of PAM targets added to a specified PAM group in the Excalibur system.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

id (integer): The unique identifier of the PAM group where to assign PAM targets to. (Required)

Query Parameters¶

This endpoint supports limited filtering and pagination as described in Excalibur v4 API Query Parameters section.

Request Body¶

N/A: This endpoint does not support request body

Response¶

Upon success, the application returns status code 200 OK and in the response body JSON data containing a paginated list of PAM targets with their total count.

total (integer): The total number of PAM targets associated with this PAM group.
entities (array): A list of PAM targets, each with the following parameters:
- id (integer): The unique identifier of the PAM target.
- tenantID (integer, optional):
- name (string): The name of the PAM target, used for identification in the system.
- description (string, optional): An optional description of the PAM target to provide context.
- type (string): The type of the PAM target. Can be either “RDP”, “SSH”, “VNC” or “Web”. (Required)
- hostname (string): The hostname or IP address of the PAM target. (Optional)
- port (integer): The port for the service, typically 22 for SSH, 3389 for RDP and 5900 for VNC. (Optional)
- url (string): The URL of the PAM target. Only set for Web targets. (Optional)
- peerVerificationStatus (string, enum): The status of peer-verification for the current user. Can be one of: “PENDING”, “APPROVED”, “DENIED”, “CLOSED” or “TIMEOUTED”.
- peerVerificationExpiresAt: (string, optional): The date when the peer-verification expires.

Example of response body:

{
  "total": 123,
  "entities": [
    {
      "id": 1234,
      "name": "Corporate SSH Server",
      "description": "SSH target for secure corporate network access",
      "hostname": "ssh.example.com",
      "port": 22,
      "type": "SSH"
    },
    {
      "id": 2345,
      "name": "Corporate RDP Server",
      "description": "RDP target for secure corporate network access",
      "hostname": "rdp.example.com",
      "port": 3389,
      "type": "RDP"
    },
    {
      "id": 3456,
      "name": "Corporate VNC Server",
      "description": "VNC target for secure corporate network access",
      "hostname": "vnc.example.com",
      "port": 5900,
      "type": "VNC"
    },
    {
      "id": 4567,
      "name": "Corporate Web Server",
      "description": "Web target for secure corporate network access",
      "type": "Web",
      "url": "web.example.com"
    }
  ]
}

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X GET {base_url}/api/v1/pamGroups/{id}/targets \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json"

Get List of PAM Targets in PAM Group in Tenant¶

Endpoint GET /api/v1/tenants/{tenantIdOrSlug}/pamGroups/{id}/targets
Permissions: pam_groups_read and pam_targets_read_all

This endpoint allows clients to retrieve a list of PAM targets added to a specified PAM group in the Excalibur system in a specified tenant.

Request Headers¶

Authorization: Bearer {access_token} The access token obtained via the OAuth 2.0 client credentials flow (see Obtaining Client Credentials).

Path Parameters¶

tenantIdOrSlug (string or integer): The unique identifier or slug of the tenant.
id (integer): The unique identifier of the PAM group where to assign PAM targets to. (Required)

Query Parameters¶

This endpoint supports limited filtering and pagination as described in Excalibur v4 API Query Parameters section.

Request Body¶

N/A: This endpoint does not support request body

Response¶

Upon success, the application returns status code 200 OK and in the response body JSON data containing a paginated list of PAM targets with their total count.

total (integer): The total number of PAM targets associated with this PAM group.
entities (array): A list of PAM targets, each with the following parameters:
- id (integer): The unique identifier of the PAM target.
- tenantID (integer, optional):
- name (string): The name of the PAM target, used for identification in the system.
- description (string, optional): An optional description of the PAM target to provide context.
- type (string): The type of the PAM target. Can be either “RDP”, “SSH”, “VNC” or “Web”. (Required)
- hostname (string): The hostname or IP address of the PAM target. (Optional)
- port (integer): The port for the service, typically 22 for SSH, 3389 for RDP and 5900 for VNC. (Optional)
- url (string): The URL of the PAM target. Only set for Web targets. (Optional)
- peerVerificationStatus (string, enum): The status of peer-verification for the current user. Can be one of: “PENDING”, “APPROVED”, “DENIED”, “CLOSED” or “TIMEOUTED”.
- peerVerificationExpiresAt: (string, optional): The date when the peer-verification expires.

Example of response body:

{
  "total": 123,
  "entities": [
    {
      "id": 1234,
      "name": "Corporate SSH Server",
      "description": "SSH target for secure corporate network access",
      "hostname": "ssh.example.com",
      "port": 22,
      "type": "SSH"
    },
    {
      "id": 2345,
      "name": "Corporate RDP Server",
      "description": "RDP target for secure corporate network access",
      "hostname": "rdp.example.com",
      "port": 3389,
      "type": "RDP"
    },
    {
      "id": 3456,
      "name": "Corporate VNC Server",
      "description": "VNC target for secure corporate network access",
      "hostname": "vnc.example.com",
      "port": 5900,
      "type": "VNC"
    },
    {
      "id": 4567,
      "name": "Corporate Web Server",
      "description": "Web target for secure corporate network access",
      "type": "Web",
      "url": "web.example.com"
    }
  ]
}

In case error happens during processing request, API will respond with one of the error codes described in the Errors section.

Example¶

curl -X GET {base_url}/api/v1/tenants/my-tenant/pamGroups/{id}/targets \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json"

Use Cases¶

This section describes common scenarios how to use Excalibur v4 API in real world applications.

Creating new tenant (project)¶

When a new project needs to start utilizing Excalibur v4 PAM, a tenant within Excalibur deployment has to be created using Create Tenant API. Once a tenant is successfully created, it is assigned a requested name and generates a unique ID within Excalibur deployment. Along with a unique ID tenant, a unique key is assigned to the tenant based on the provided key or is generated from the tenant name. This key is later used as a slug in API calls for tenant management and as a tenant ID, cannot be changed later.

The client application that interacts with Excalibur v4 API should store generated ID or key (or both) for later tenant management.

As already mentioned in the Tenant management section, the tenant creation process is asynchronous and API for tenant creation returns immediately after tenant database entries are created. The rest of the tenant creation process (resource provisioning inside cluster) is asynchronous and in case the client application needs to wait for the tenant creation process to finish, it has to listen for incoming events on pre-configured webhook (see Webhooks).

Whole tenant configuration (other required API calls to setup identity store, invite users, create PAM targets etc) can be made right after tenant database entries are created and Excalibur v4 API returns tenant ID.

Configuring tenant network policy¶

As part of the tenant creation process also network policy for tenants can be specified. The purpose of network policy is to specify a list of network addresses in different formats (IPv4, IPv6, CIDR, hostnames, …), where tenant PAM related applications in the cluster can connect to. Thus it serves the purpose of a network address whitelist for tenant PAM modules. In case no addresses are specified, the PAM module has visibility to any address configured for a specific PAM target.

Network policies can be modified also after a tenant is created. For more information see Network Policy Management.

Network policy addresses are validated both on application and on architecture layers. On application layer addresses are checked when creating PAM targets to improve user experience (warn users that configured PAM target IP or hostname is out of allowed range and it will not be possible to dial session to target being created). Network addresses are validated on the architecture layer (as Network Policy cluster resource type) too, thus preventing connections to targets out of pre-configured range.

Setting up tenant Identity Store(s)¶

Identity stores are a crucial part of new tenant configuration (see Identity Stores Management). Without a valid identity store configuration it is impossible to invite users (see Invite Users to Tenant) to the tenant. Excalibur uses identity stores not only when inviting users. Identities in identity stores are checked each time a user is performing the authentication or authorization. Whole Excalibur user management process relies on the user account lifecycle within the identity store(s).

To communicate with identity stores Excalibur v4 uses LDAPs protocol and at the time of writing this supports only Microsoft Active Directory.

Excalibur leverages existing user management infrastructure, ensuring consistency and security across the organization without any further effort.

Tenants can have multiple identity stores configured. After an identity store is created within a tenant, it is assigned a unique ID, which has to be used in subsequent calls related to that identity store (for example inviting users).

Managing tenant PAM targets¶

Once a tenant is successfully created (tenant resource provisioning does not have to be finished yet), PAM targets (RDP/SSH/VNC/Web) can be created. For more information see PAM Target Management and for target creation Add RDP PAM Target and Add SSH PAM Target.

PAM targets have to be created one by one, thus separate API requests for each PAM target is required. Bulk creation for PAM targets over Excalibur v4 API is a soon-to-come feature on a roadmap, which will be using existing API endpoints for PAM target creation without breaking backward compatibility.

Newly created PAM targets do not belong to any PAM target groups, thus can be seen only by tenant Administrators. In order for the PAM target to be seen by other users (different roles), the PAM target group has to be created by the tenant Administrator and the PAM target has to be assigned to the group. Afterwards system administrators can grant access to PAM target groups for specific user groups configured within the tenant.

PAM target groups and their relations to user groups within tenants can be configured over Excalibur v4 API too, but for now documentation for those endpoints is not part of this integration manual.

Inviting users to tenant¶

As per other use case scenarios, for inviting users to a tenant, its resource provisioning does not have to be finished and users can be invited. Before any user can be invited to a tenant, at least one identity store has to be created successfully. For more information see Identity Stores Management.

Inviting users to the tenant is done using Invite Users to Tenant API. In order to invite users, the client application has to pass an array of user unique IDs (In the case of Active Directory identity store, user objectGUID is used as a user unique identifier / uuid) within the request body along with identity store ID and list of user group IDs, where invited users will be assigned.

Excalibur v4 offers 3 built-in roles for system wide access and 3 built-in roles for each tenant scoped access. The roles are Administrators, Auditors and Users. The roles are described as follows:

Role	Scope of access
Administrators	Read-write access to everything within the System/Tenant
Auditors	Readonly access to everything within the System/Tenant
Users	Read-write access to some parts within the System/Tenant

In system scope, the unique identifiers (IDs) are as follows:

Administrators - 1
Auditors - 2
Users - 3

In tenant scope, the unique identifiers are dynamically assigned, so it is necessary to look into your tenant to see what specific identifiers have they got assigned.

Adding PAM targets to tenant¶

To add PAM targets to existing tenants is following the same principles as described in Managing tenant PAM targets. PAM targets can be added / removed from the tenant at any time while the tenant exists.

Removing PAM targets from tenant¶

As for PAM target addition, the same applies to their removal, when some PAM target virtual machine is decommissioned. PAM targets can be removed one by one utilizing Delete PAM Target API.

Every PAM target in the tenant has its own unique ID, thus targets can be deleted also in batches using Delete Multiple PAM Targets API.

Once the PAM target is deleted, the target will no longer be accessible and available in PAM targets view, but historical session records will remain available for auditing purposes. From the session detail view, PAM target audit values can be accessed.

Update network policy addresses¶

In case it is necessary to update network policy with new addresses in order for newly created PAM targets to be reachable from the tenant's Excalibur PAM module, tenant network policy has to be updated utilizing Update Network Policy API.

As network policy resources in the cluster cant be updated and has to be recreated every time the list of allowed network addresses change, the client application has to send the whole list of allowed addresses in update request.

Invite new users¶

Users can be managed for the whole time the tenant exists. Inviting new users follows the same principles as described in the Inviting users to tenant section. Be careful, all users (even Administrators or Auditors) should be in Users group, in addition to any other group they may be part of.

Notes¶

This document will be iterated based on the implemented changes and project needs

Excalibur v4 REST API documentation 4.18.0¶

Introduction¶

Overview¶

Audience¶

List of Abbreviations¶

Getting Started¶

REST API¶

Key REST Principles¶

HTTP Methods and Their Purposes¶

Errors¶

HTTP status codes¶

Application errors¶

OAuth 2.0 Authorization¶

Obtaining Client Credentials¶

Login to Excalibur Dashboard¶

Fill in required fields for newly created OAuth client¶

Copy and store credentials¶

API Endpoints and Environment Setup¶

Authenticating Requests with OAuth 2.0 Client Credentials Flow¶

Request Access Token¶

Receive Token¶

Include Token in Requests¶

Token expiration¶

Webhooks¶

Creating webhook¶

Select OAuth client¶

Add new webhook¶

Fill in required fields for newly created Webhook¶

Editing or deleting webhook¶

Testing webhook¶

Content of webhook messages¶

Common structure¶

Content of tenant creation message¶

Content of test event message¶

API¶

Query Parameters¶

Filtering¶

Filtering Operators¶

Equality Operator (=)¶

Greater than Operator (>)¶

Less than Operator (\<)¶

Greater than or equal to Operator (>=)¶

Less than or equal to (\<=)¶

Not Equal Operator (\<>)¶

Contains (LIKE) Operator (%)¶

Starts with Operator (%-)¶

End with Operator (-%)¶

Combining Operators¶

And Operator (and)¶

Or Operator (or)¶

Sorting in the API¶

Sorting Features¶

Ascending sorting¶

Descending sorting¶

Favor empty values first¶

Multiple sorting¶

Column selection¶

Pagination¶

Combined Usage¶

API endpoints¶

Tenant management¶

Create Tenant¶

Request Headers¶

Path Parameters¶

Query Parameters¶

Request Body¶

Response¶

Example¶

Get Tenant by ID or Slug¶

Request Headers¶

Path Parameters¶

Query Parameters¶

Request Body¶

Response¶

Example¶

Get All Tenants¶

Request Headers¶

Path Parameters¶

Query Parameters¶

Request Body¶