### Setup Environment Variables

Source: https://boxyhq.com/docs/jackson/local-development

Copy the example environment variables file to create your local configuration. Refer to the environment variables documentation for details on setting them.

```bash
cp .env.example .env  
```

--------------------------------

### Setup Local Development Databases

Source: https://boxyhq.com/docs/jackson/local-development

Initialize database instances for local development using Docker. This command requires Docker to be installed and running.

```bash
npm run dev-dbs  
```

--------------------------------

### Copy Environment Example File

Source: https://boxyhq.com/docs/jackson/deploy/service

Copy the example environment file to create your own .env file for configuration.

```bash
cp .env.example .env
```

--------------------------------

### Install Node.js Dependencies

Source: https://boxyhq.com/docs/jackson/local-development

Install all required Node.js dependencies for the project using npm. Ensure you have Node.js and npm installed.

```bash
npm install  
```

--------------------------------

### Start Ory Polis Service

Source: https://boxyhq.com/docs/jackson/deploy/service

Start the Ory Polis service after building the application.

```bash
npm run start
```

--------------------------------

### Install Ory Elements for Next.js

Source: https://boxyhq.com/docs

Install the necessary Ory packages for your Next.js project. This command is typically run when starting a new project or integrating Ory Elements.

```bash
npm install @ory/elements-react @ory/nextjs
```

--------------------------------

### Install Node.js Dependencies

Source: https://boxyhq.com/docs/jackson/deploy/service

Install all the necessary Node.js dependencies for Ory Polis using npm.

```bash
npm install
```

--------------------------------

### Start Ory Polis Development Server

Source: https://boxyhq.com/docs/jackson/local-development

Start the Ory Polis development server. This command compiles and runs the application in development mode.

```bash
npm run dev  
```

--------------------------------

### Install Jackson NPM Library

Source: https://boxyhq.com/docs/jackson/deploy/npm-library

Install the Ory Polis npm library using npm. This is the first step to integrating SAML and OIDC functionality into your Node.js application.

```bash
npm install @boxyhq/saml-jackson
```

--------------------------------

### Install Directory Sync NPM Package

Source: https://boxyhq.com/docs/directory-sync/getting-started

Install the BoxyHQ SAML Jackson NPM package to use Directory Sync as a library in your Node.js application.

```bash
npm i --save @boxyhq/saml-jackson  

```

--------------------------------

### Get Directories by Tenant and Product (Node.js)

Source: https://boxyhq.com/docs/directory-sync/api-reference

Retrieve a list of directory connections for a specific tenant and product using the Node.js SDK. Requires the directorySyncController to be initialized.

```javascript
const tenant = "ory"
const product = "polis"

const { data, error } = await directorySyncController.directories.getByTenantAndProduct(tenant, product)
```

--------------------------------

### Get Directories by Tenant and Product (Shell)

Source: https://boxyhq.com/docs/directory-sync/api-reference

Retrieve a list of directory connections using a cURL command. Filters by tenant and product query parameters and requires an API key for authorization.

```shell
curl --request GET \
  --url 'http://localhost:5225/api/v1/directory-sync?tenant=ory&product=polis' \
  --header 'Authorization: Api-Key secret' \
  --header 'Content-Type: application/json'
```

--------------------------------

### Example Webhook Signature

Source: https://boxyhq.com/docs/directory-sync/webhooks

An example of the Ory-Signature header format, which includes a timestamp and a signature for verification.

```text
Ory-Signature: t=1545010989801,s=xxxx  

```

--------------------------------

### dsync.created Event Example

Source: https://boxyhq.com/docs/directory-sync/events

This event is triggered when a new directory connection is created. Ensure WEBHOOK_URL and WEBHOOK_SECRET are configured.

```json
{
  "event": "dsync.created",
  "tenant": "ory",
  "product": "demo",
  "data": {
    "id": "d8aa6c93-c960-4925-9b31-4a4d2ad3bb44",
    "name": "Okta Directory",
    "type": "okta-scim-v2"
  }
}
```

--------------------------------

### Get directories

Source: https://boxyhq.com/docs/directory-sync/api-reference

Retrieves a list of directories associated with a specific tenant and product. A tenant can have multiple directories, even for the same product.

```APIDOC
## Get directories

### Description
Get the list of directories for the given tenant and product. A tenant can have multiple directories for same or different products.

### Method
GET

### Endpoint
/api/v1/directory-sync

### Parameters
#### Query Parameters
- **tenant** (string) - Required - The tenant ID.
- **product** (string) - Required - The product ID.

### Response
#### Success Response (200)
- **data** (array) - A list of directory objects.
  - Each object contains directory details similar to the 'Create a new directory' response.
- **error** (null) - Indicates no error occurred.

#### Response Example
```json
{
  "data": [
    {
      "id": "58b5cd9dfaa39d47eb8f5f88631f9a629a232016",
      "name": "App",
      "tenant": "ory",
      "product": "polis",
      "type": "onelogin-scim-v2",
      "log_webhook_events": false,
      "scim": {
        "path": "/api/scim/v2.0/58b5cd9dfaa39d47eb8f5f88631f9a629a232016",
        "secret": "IJzAoevjD_liiiy-VkDtXg",
        "endpoint": "http://localhost:5225/api/scim/v2.0/58b5cd9dfaa39d47eb8f5f88631f9a629a232016"
      },
      "webhook": {
        "endpoint": "https://my-cool-app.com/webhook",
        "secret": "my-secret"
      }
    }
  ],
  "error": null
}
```
```

--------------------------------

### Get Connections

Source: https://boxyhq.com/docs/jackson/sso-flow

Retrieves SAML/OIDC connections configured for a tenant/product. You can query using either `clientID` or a `tenant` and `product` combination.

```APIDOC
## GET /api/v1/connections

### Description
Retrieves SAML/OIDC connections configured for a tenant/product. This can be used to check and display the details to your customers. You can use either `clientID` or `tenant` and `product` combination.

### Method
GET

### Endpoint
/api/v1/connections

### Parameters
#### Query Parameters
- **tenant** (string) - Required/Optional - The tenant identifier.
- **product** (string) - Required/Optional - The product identifier.
- **clientID** (string) - Required/Optional - The client ID of the connection.

### Request Example
```curl
curl -G --location 'http://localhost:5225/api/v1/connections' \
--header 'Authorization: Api-Key <Ory Polis API Key>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'tenant=ory.com' \
--data-urlencode 'product=demo'
```

```curl
curl -G --location 'http://localhost:5225/api/v1/connections' \
--header 'Authorization: Api-Key <Ory Polis API Key>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'clientID=<Client ID>'
```

### Response
#### Success Response (200)
- **idpMetadata.provider** (string) - Indicates the domain of your Identity Provider.
- **oidcProvider.provider** (string) - Indicates the domain of your Identity Provider.

If an empty JSON payload is returned then we do not have any connection stored for the attributes you requested.
```

--------------------------------

### dsync.activated Event Example

Source: https://boxyhq.com/docs/directory-sync/events

This event is triggered when a directory connection is activated. Ensure WEBHOOK_URL and WEBHOOK_SECRET are configured.

```json
{
  "event": "dsync.activated",
  "tenant": "ory",
  "product": "demo",
  "data": {
    "id": "d8aa6c93-c960-4925-9b31-4a4d2ad3bb44",
    "name": "Okta Directory",
    "type": "okta-scim-v2"
  }
}
```

--------------------------------

### Get Directory User (Node.js)

Source: https://boxyhq.com/docs/directory-sync/api-reference

Retrieve a specific user's details by their ID, tenant, and product. The userId must be a valid UUID.

```javascript
const tenant = "ory"
const product = "flex"
const userId = "ebc31d6e-7d62-4f81-b9e5-eb5f1a04ee92"

const users = await directorySyncController.users.setTenantAndProduct(tenant, product).get(userId)
```

--------------------------------

### Create SAML Connection Response

Source: https://boxyhq.com/docs/jackson/deploy/npm-library

Example response object after successfully creating a SAML connection. It includes generated client ID and secret, along with IdP metadata and certificates.

```json
{
  "defaultRedirectUrl": "https://your-app.com/sso/callback",
  "redirectUrl": ["https://your-app.com/*"],
  "tenant": "ory",
  "product": "your-app",
  "clientID": "f7c909a5c72a5535847acf32558b2429a5172dd6",
  "clientSecret": "cc6ba07bc42c2f449c9b0a3cc41c256dea08f705e1b44fdc",
  "forceAuthn": false,
  "idpMetadata": {
    "sso": {
      "postUrl": "https://mocksaml.com/api/saml/sso",
      "redirectUrl": "https://mocksaml.com/api/saml/sso"
    },
    "slo": {},
    "entityID": "https://saml.example.com/entityid",
    "thumbprint": "d797f3829882233d3f01e49643f6a1195f242c94",
    "validTo": "Jul  1 21:46:38 3021 GMT",
    "loginType": "idp",
    "provider": "saml.example.com"
  },
  "certs": {
    "publicKey": "-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----\r\n",
    "privateKey": "-----BEGIN RSA PRIVATE KEY----- ... -----END RSA PRIVATE KEY-----\r\n"
  }
}
```

--------------------------------

### List Groups

Source: https://boxyhq.com/docs/directory-sync/api-reference

Retrieves a list of all groups within a specified tenant and product. This is useful for getting an overview of available groups.

```APIDOC
## GET /api/v1/directory-sync/groups

### Description
Retrieves a list of all groups within a specified tenant and product.

### Method
GET

### Endpoint
/api/v1/directory-sync/groups

#### Query Parameters
- **tenant** (string) - Required - The tenant identifier.
- **product** (string) - Required - The product identifier.

### Response
#### Success Response (200)
- **data** (array) - An array of group objects.
  - **id** (string) - The unique identifier for the group.
  - **name** (string) - The name of the group.
  - **raw** (object) - The raw group data from the source.

### Response Example
```json
{
  "data": [
    {
      "id": "44d08c0e-d185-4a5e-80a6-b47a717ffaa5",
      "name": "Developers",
      "raw": {
        "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
        "displayName": "Developers",
        "members": [
          {
            "value": "6296f71e-15fd-4af4-86ee-d6623b3ef1a4",
            "display": "aswin@ory.com"
          },
          {
            "value": "ebc31d6e-7d62-4f81-b9e5-eb5f1a04ee92",
            "display": "kiran@ory.com"
          }
        ],
        "id": "44d08c0e-d185-4a5e-80a6-b47a717ffaa5"
      }
    }
  ],
  "error": null
}
```
```

--------------------------------

### Get Directory User

Source: https://boxyhq.com/docs/directory-sync/api-reference

Retrieves the details of a specific user within a directory by their user ID. Requires tenant, product, and user ID.

```APIDOC
## GET /api/v1/directory-sync/users/{userId}

### Description
Gets the details of a directory user.

### Method
GET

### Endpoint
/api/v1/directory-sync/users/{userId}

### Path Parameters
- **userId** (string) - Required - The unique identifier of the user.

### Query Parameters
- **tenant** (string) - Required - The tenant identifier.
- **product** (string) - Required - The product identifier.

### Request Example
```javascript
const tenant = "ory"
const product = "flex"
const userId = "ebc31d6e-7d62-4f81-b9e5-eb5f1a04ee92"

const users = await directorySyncController.users.setTenantAndProduct(tenant, product).get(userId)
```

### Response
#### Success Response (200)
- **data** (object) - The user object.
  - **id** (string) - The unique identifier for the user.
  - **first_name** (string) - The first name of the user.
  - **last_name** (string) - The last name of the user.
  - **email** (string) - The email address of the user.
  - **active** (boolean) - Indicates if the user account is active.
  - **raw** (object) - Raw user data from the source.
- **error** (object) - An error object if the request failed, otherwise null.

#### Response Example
```json
{
  "data": {
    "id": "ebc31d6e-7d62-4f81-b9e5-eb5f1a04ee92",
    "first_name": "Kiran",
    "last_name": "Krishnan",
    "email": "kiran@ory.com",
    "active": true,
    "raw": {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
      "userName": "kiran@ory.com",
      "name": {
        "givenName": "Kiran",
        "familyName": "Krishnan"
      },
      "emails": [
        {
          "primary": true,
          "value": "kiran@ory.com",
          "type": "work"
        }
      ],
      "displayName": "Kiran Krishnan",
      "addresses": [
        {
          "primary": true,
          "region": "Kerala"
        }
      ],
      "locale": "en-US",
      "externalId": "00u3e3cmpdDydXdzV5d7",
      "groups": [],
      "active": true,
      "id": "ebc31d6e-7d62-4f81-b9e5-eb5f1a04ee92"
    }
  },
  "error": null
}
```
```

--------------------------------

### Create OIDC Connection Response

Source: https://boxyhq.com/docs/jackson/deploy/npm-library

Example response object after successfully creating an OIDC connection. It includes generated client ID and secret, and the OIDC provider configuration.

```json
{
  "defaultRedirectUrl": "https://your-app.com/sso/callback",
  "redirectUrl": ["https://your-app.com/*"],
  "tenant": "ory",
  "product": "your-app",
  "clientID": "749f95c4bd02b4adb6c0633249e70d5ad45b75e2",
  "clientSecret": "2d730ac71c74e7d49dccf362c9a61005b6246cc65d6d0fa4",
  "oidcProvider": {
    "discoveryUrl": "https://accounts.google.com/.well-known/openid-configuration",
    "clientId": "<OpenID Client ID>",
    "clientSecret": "<OpenID Client Secret>",
    "provider": "accounts.google.com"
  }
}
```

--------------------------------

### Get Directory by ID (Node.js)

Source: https://boxyhq.com/docs/directory-sync/api-reference

Retrieve the details of a specific directory connection by its unique ID using the Node.js SDK. Ensure the directorySyncController is initialized.

```javascript
const directoryId = "58b5cd9dfaa39d47eb8f5f88631f9a629a232016"

const { data, error } = await directorySyncController.directories.get(directoryId)
```

--------------------------------

### Get Directory User (Shell)

Source: https://boxyhq.com/docs/directory-sync/api-reference

Use this cURL command to fetch a specific user's details using their ID, tenant, and product. Ensure the Authorization header contains a valid API key.

```shell
curl --request GET \
  --url 'http://localhost:5225/api/v1/directory-sync/users/ebc31d6e-7d62-4f81-b9e5-eb5f1a04ee92?tenant=ory&product=polis' \
  --header 'Authorization: Api-Key secret' \
  --header 'Content-Type: application/json'
```

--------------------------------

### Build Ory Polis Application

Source: https://boxyhq.com/docs/jackson/deploy/service

Build the Ory Polis application for production.

```bash
npm run build
```

--------------------------------

### Add SAML Connection using API

Source: https://boxyhq.com/docs/jackson/sso-flow

Use this API call to set up a SAML connection. Provide either `encodedRawMetadata` or `metadataUrl` with your IdP/SP metadata. Ensure `tenant` and `product` are set correctly.

```curl
curl --location --request POST 'http://localhost:5225/api/v1/connections' \
--header 'Authorization: Api-Key <Ory Polis API Key>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'encodedRawMetadata=Base64(<IdP/SP metadata XML>)' \
--data-urlencode 'defaultRedirectUrl=http://localhost:3366/login/saml' \
--data-urlencode 'redirectUrl=http://localhost:3366/*' \
--data-urlencode 'redirectUrl=http://localhost:3000/*' \
--data-urlencode 'tenant=ory.com' \
--data-urlencode 'product=demo' \
--data-urlencode 'name=demo-connection' \
--data-urlencode 'description=Demo SAML connection'
```

--------------------------------

### Initialize Directory Sync Controller

Source: https://boxyhq.com/docs/directory-sync/api-reference

Initialize the Directory Sync controller with custom options. Note that this initialization is asynchronous and cannot be run at the top level.

```javascript
const opts = {
  externalUrl: "https://my-cool-app.com",
  db: {
    engine: "mongo",
    url: "mongodb://localhost:27017/my-cool-app",
  },
}

let directorySyncController

// Please note that the initialization of @boxyhq/saml-jackson is async, you cannot run it at the top level.
async function init() {
  const jackson = await require("@boxyhq/saml-jackson").controllers(opts)
  directorySyncController = jackson.directorySyncController
}
```

--------------------------------

### List Directory Users (Node.js)

Source: https://boxyhq.com/docs/directory-sync/api-reference

Use this method to retrieve all users within a specified tenant and product. Ensure the directorySyncController is properly initialized.

```javascript
const tenant = "ory"
const product = "polis"

const { data, error } = await directorySyncController.users.setTenantAndProduct(tenant, product).getAll()
```

--------------------------------

### Get a directory

Source: https://boxyhq.com/docs/directory-sync/api-reference

Retrieves the detailed information for a specific directory using its unique identifier.

```APIDOC
## Get a directory

### Description
Get the details of a directory by its unique id.

### Method
GET

### Endpoint
/api/v1/directory-sync/{directoryId}

### Parameters
#### Path Parameters
- **directoryId** (string) - Required - The unique ID of the directory.

### Response
#### Success Response (200)
- **data** (object) - Contains the directory details.
  - The structure is identical to the 'Create a new directory' response data.
- **error** (null) - Indicates no error occurred.

#### Response Example
```json
{
  "data": {
    "id": "58b5cd9dfaa39d47eb8f5f88631f9a629a232016",
    "name": "App",
    "tenant": "ory",
    "product": "polis",
    "type": "onelogin-scim-v2",
    "log_webhook_events": false,
    "scim": {
      "path": "/api/scim/v2.0/58b5cd9dfaa39d47eb8f5f88631f9a629a232016",
      "secret": "IJzAoevjD_liiiy-VkDtXg",
      "endpoint": "http://localhost:5225/api/scim/v2.0/58b5cd9dfaa39d47eb8f5f88631f9a629a232016"
    },
    "webhook": {
      "endpoint": "https://my-cool-app.com/webhook",
      "secret": "my-secret"
    }
  },
  "error": null
}
```
```

--------------------------------

### List Directory Users (Shell)

Source: https://boxyhq.com/docs/directory-sync/api-reference

This cURL command lists all users for a given tenant and product. Replace placeholders with your actual tenant, product, and API key.

```shell
curl --request GET \
  --url 'http://localhost:5225/api/v1/directory-sync/users?tenant=ory&product=polis' \
  --header 'Authorization: Api-Key secret' \
  --header 'Content-Type: application/json'
```

--------------------------------

### Get SAML/OIDC Connections

Source: https://boxyhq.com/docs/jackson/deploy/npm-library

Retrieves the details of an existing SAML or OIDC Single Sign-On connection.

```APIDOC
## Get SAML/OIDC Connections

### Description
Get the details of an existing SAML or OIDC Single Sign-On connection.

### Method
`connection.getConnections`

### Parameters
#### Body Parameters (choose one option)
Option 1:
- **tenant** (string) - Required - The tenant identifier.
- **product** (string) - Required - The product identifier.

Option 2:
- **clientID** (string) - Required - The client ID of the SSO Connection to be retrieved.

### Response
#### Success Response (200)
An array of connection objects, each containing details like `defaultRedirectUrl`, `redirectUrl`, `tenant`, `product`, `clientID`, `clientSecret`, `forceAuthn`, `idpMetadata`, and `certs`.

### Request Example
```javascript
// Using tenant and product
await connection.getConnections({
  tenant: "ory",
  product: "your-app",
});

// Using the client ID
await connection.getConnections({
  clientID: "<clientID of the SSO Connection to be retrieved>."
});
```

### Response Example
```json
[
  {
    "defaultRedirectUrl": "https://your-app.com/sso/callback",
    "redirectUrl": ["https://your-app.com/*"],
    "tenant": "ory",
    "product": "your-app",
    "clientID": "...",
    "clientSecret": "...",
    "forceAuthn": false,
    "idpMetadata": {
      "sso": {
        "postUrl": "https://mocksaml.com/api/saml/sso",
        "redirectUrl": "https://mocksaml.com/api/saml/sso"
      },
      "slo": {},
      "entityID": "https://saml.example.com/entityid",
      "thumbprint": "d797f3829882233d3f01e49643f6a1195f242c94",
      "validTo": "Jul  1 21:46:38 3021 GMT",
      "loginType": "idp",
      "provider": "saml.example.com"
    },
    "certs": {
      "publicKey": "-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----\r\n",
      "privateKey": "-----BEGIN RSA PRIVATE KEY----- ... -----END RSA PRIVATE KEY-----\r\n"
    }
  }
]
```
```

--------------------------------

### dsync.deleted Event Example

Source: https://boxyhq.com/docs/directory-sync/events

This event is triggered when a directory connection is deleted. Ensure WEBHOOK_URL and WEBHOOK_SECRET are configured.

```json
{
  "event": "dsync.deleted",
  "tenant": "ory",
  "product": "demo",
  "data": {
    "id": "d8aa6c93-c960-4925-9b31-4a4d2ad3bb44",
    "name": "Okta Directory",
    "type": "okta-scim-v2"
  }
}
```

--------------------------------

### List All Groups - Node.js

Source: https://boxyhq.com/docs/directory-sync/api-reference

Use this method to retrieve all groups for a given tenant and product. Ensure the tenant and product are correctly set before calling.

```javascript
const tenant = "ory"
const product = "polis"
const users = await directorySyncController.groups.setTenantAndProduct(tenant, product).getAll()
```

--------------------------------

### dsync.deactivated Event Example

Source: https://boxyhq.com/docs/directory-sync/events

This event is triggered when a directory connection is deactivated. Ensure WEBHOOK_URL and WEBHOOK_SECRET are configured.

```json
{
  "event": "dsync.deactivated",
  "tenant": "ory",
  "product": "demo",
  "data": {
    "id": "d8aa6c93-c960-4925-9b31-4a4d2ad3bb44",
    "name": "Okta Directory",
    "type": "okta-scim-v2"
  }
}
```

--------------------------------

### Run PlanetScale Database Migration

Source: https://boxyhq.com/docs/jackson/deploy/service

Execute the database migration script for PlanetScale. Ensure you replace `<PlanetScale connection URL>` with your actual connection string.

```bash
cd npm && PLANETSCALE_URL=<PlanetScale connection URL> npm run db:migration:run:planetscale
```

--------------------------------

### List All Groups - Shell

Source: https://boxyhq.com/docs/directory-sync/api-reference

Use this cURL command to list all groups for a given tenant and product. Replace 'secret' with your actual API key.

```shell
curl --request GET \
  --url 'http://localhost:5225/api/v1/directory-sync/groups?tenant=ory&product=polis' \
  --header 'Authorization: Api-Key secret' \
  --header 'Content-Type: application/json'
```

--------------------------------

### Create Directory Connection (Node.js)

Source: https://boxyhq.com/docs/directory-sync/api-reference

Create a new directory connection using the Node.js SDK. Ensure the directorySyncController is initialized before use.

```javascript
const { data, error } = await directorySyncController.directories.create({
  name: "App",
  tenant: "ory",
  product: "polis",
  type: "onelogin-scim-v2",
  webhook_url: "https://my-cool-app.com/webhook",
  webhook_secret: "my-secret",
})
```

--------------------------------

### Access Ory Polis Local Service

Source: https://boxyhq.com/docs/jackson/local-development

The Ory Polis service is accessible locally at this URL. Use this to test your setup.

```http
http://localhost:5225  
```

--------------------------------

### Check Ory Polis API Health

Source: https://boxyhq.com/docs/jackson/local-development

Visit this URL to verify that the Ory Polis service has started successfully and is responding to requests.

```http
http://localhost:5225/api/hello  
```

--------------------------------

### Get Directory Group

Source: https://boxyhq.com/docs/directory-sync/api-reference

Retrieves the details of a specific directory group by its ID. This is useful for inspecting a single group's information.

```APIDOC
## GET /api/v1/directory-sync/groups/{groupId}

### Description
Retrieves the details of a specific directory group by its ID.

### Method
GET

### Endpoint
/api/v1/directory-sync/groups/{groupId}

#### Path Parameters
- **groupId** (string) - Required - The unique identifier of the group.

#### Query Parameters
- **tenant** (string) - Required - The tenant identifier.
- **product** (string) - Required - The product identifier.

### Response
#### Success Response (200)
- **data** (object) - The group object.
  - **id** (string) - The unique identifier for the group.
  - **name** (string) - The name of the group.
  - **raw** (object) - The raw group data from the source.
  - **members** (array) - An array of members associated with the group.
    - **group_id** (string) - The ID of the group.
    - **user_id** (string) - The ID of the user.

### Response Example
```json
{
  "data": {
    "id": "44d08c0e-d185-4a5e-80a6-b47a717ffaa5",
    "name": "Developers",
    "raw": {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
      "displayName": "Developers",
      "members": [
        {
          "value": "6296f71e-15fd-4af4-86ee-d6623b3ef1a4",
          "display": "aswin@ory.com"
        },
        {
          "value": "ebc31d6e-7d62-4f81-b9e5-eb5f1a04ee92",
          "display": "kiran@ory.com"
        }
      ],
      "id": "44d08c0e-d185-4a5e-80a6-b47a717ffaa5"
    },
    "members": [
      {
        "group_id": "44d08c0e-d185-4a5e-80a6-b47a717ffaa5",
        "user_id": "6296f71e-15fd-4af4-86ee-d6623b3ef1a4"
      },
      {
        "group_id": "44d08c0e-d185-4a5e-80a6-b47a717ffaa5",
        "user_id": "ebc31d6e-7d62-4f81-b9e5-eb5f1a04ee92"
      }
    ]
  },
  "error": null
}
```
```

--------------------------------

### Create a new directory

Source: https://boxyhq.com/docs/directory-sync/api-reference

Allows for the creation of a new directory connection. You can specify details such as the directory name, tenant, product, provider type, and webhook configurations.

```APIDOC
## Create a new directory

### Description
Create a new directory connection.

### Method
POST

### Endpoint
/api/v1/directory-sync

### Parameters
#### Request Body
- **name** (string) - Required - The name of the directory.
- **tenant** (string) - Required - The tenant ID.
- **product** (string) - Required - The product ID.
- **type** (string) - Required - The directory provider type.
- **webhook_url** (string) - Optional - The webhook URL.
- **webhook_secret** (string) - Optional - The webhook secret.

### Request Example
```json
{
  "name": "App",
  "tenant": "ory",
  "product": "polis",
  "type": "onelogin-scim-v2",
  "webhook_url": "https://my-cool-app.com/webhook",
  "webhook_secret": "my-secret"
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains the created directory details.
  - **id** (string) - The unique identifier for the directory.
  - **name** (string) - The name of the directory.
  - **tenant** (string) - The tenant ID.
  - **product** (string) - The product ID.
  - **type** (string) - The directory provider type.
  - **log_webhook_events** (boolean) - Indicates if webhook events are logged.
  - **scim** (object) - SCIM configuration details.
    - **path** (string) - The SCIM endpoint path.
    - **secret** (string) - The SCIM endpoint secret.
    - **endpoint** (string) - The SCIM endpoint URL.
  - **webhook** (object) - Webhook configuration details.
    - **endpoint** (string) - The webhook URL.
    - **secret** (string) - The webhook secret.
- **error** (null) - Indicates no error occurred.

#### Response Example
```json
{
  "data": {
    "id": "58b5cd9dfaa39d47eb8f5f88631f9a629a232016",
    "name": "App",
    "tenant": "ory",
    "product": "polis",
    "type": "onelogin-scim-v2",
    "log_webhook_events": false,
    "scim": {
      "path": "/api/scim/v2.0/58b5cd9dfaa39d47eb8f5f88631f9a629a232016",
      "secret": "IJzAoevjD_liiiy-VkDtXg",
      "endpoint": "http://localhost:5225/api/scim/v2.0/58b5cd9dfaa39d47eb8f5f88631f9a629a232016"
    },
    "webhook": {
      "endpoint": "https://my-cool-app.com/webhook",
      "secret": "my-secret"
    }
  },
  "error": null
}
```
```

--------------------------------

### Retrieve SAML/OIDC Connections by Tenant/Product

Source: https://boxyhq.com/docs/jackson/sso-flow

Use this endpoint to fetch SAML or OIDC connections configured for a specific tenant and product. Ensure you have an API key for authorization.

```curl
curl -G --location 'http://localhost:5225/api/v1/connections' \

--header 'Authorization: Api-Key <Ory Polis API Key>' \

--header 'Content-Type: application/x-www-form-urlencoded' \

--data-urlencode 'tenant=ory.com' \

--data-urlencode 'product=demo'
```

--------------------------------

### Sample Webhook Request Payload

Source: https://boxyhq.com/docs/directory-sync/webhooks

This is an example of the JSON payload sent in a POST request to your webhook endpoint when a change occurs in a directory user or group.

```json
POST /your-webhook-endpoint  

Content-Type: application/json  

Ory-Signature: t=xxx,s=xxxx  

  

{
  "directory_id": "58b5cd9dfaa39d47eb8f5f88631f9a629a232016",
  "event": "user.created",
  "tenant": "ory",
  "product": "polis",
  "data": {
    "id": "038e767b-9bc6-4dbd-975e-fbc38a8e7d82",
    "first_name": "Deepak",
    "last_name": "Prabhakara",
    "email": "deepak@ory.com",
    "active": true,
    "raw": {...}
  }
}


```

--------------------------------

### Initialize Jackson Controllers

Source: https://boxyhq.com/docs/jackson/deploy/npm-library

Initialize the Jackson controllers asynchronously. Ensure this is not run at the top level of your application. Configuration options include external URL, SAML audience, OIDC/SAML paths, and database settings.

```typescript
import jackson, {
  type IConnectionAPIController,
  type IOAuthController,
} from '@boxyhq/saml-jackson';

let oauth: IOAuthController;
let connection: IConnectionAPIController;

(async function init() {
  const jackson = await require('@boxyhq/saml-jackson').controllers({
    externalUrl: 'https://your-app.com',
    samlAudience: 'https://saml.boxyhq.com',
    oidcPath: '/api/oauth/oidc',
    samlPath: '/api/oauth/saml',
    db: {
      engine: 'sql',
      type: 'postgres',
      url: 'postgres://postgres:postgres@localhost:5432/postgres',
    },
  });

  oauth = jackson.oauthController;
  connection = jackson.connectionAPIController;
})();
```

--------------------------------

### Setting API Keys

Source: https://boxyhq.com/docs/jackson/deploy/env-variables

Configure a comma-separated list of API keys for authenticating API requests. The `Authorization` header must include one of these keys.

```bash
API_KEYS=key1,key2,key3
```

--------------------------------

### Get Directory Group Details - Node.js

Source: https://boxyhq.com/docs/directory-sync/api-reference

Retrieve the details of a specific directory group by its ID. The tenant and product must be set prior to calling this method.

```javascript
const tenant = "ory"
const product = "polis"
const groupId = "44d08c0e-d185-4a5e-80a6-b47a717ffaa5"
const users = await directorySyncController.groups.setTenantAndProduct(tenant, product).get(groupId)
```

--------------------------------

### Add OIDC Connection using API

Source: https://boxyhq.com/docs/jackson/sso-flow

Use this API call to set up an OIDC connection. Provide the `oidcDiscoveryUrl`, `oidcClientId`, and `oidcClientSecret` obtained from your OIDC provider. Ensure `tenant` and `product` are set correctly.

```curl
curl --location --request POST 'http://localhost:5225/api/v1/connections' \
--header 'Authorization: Api-Key <Ory Polis API Key>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'defaultRedirectUrl=http://localhost:3366/login/oidc' \
--data-urlencode 'oidcDiscoveryUrl=<well-known url of OIDC Provider>' \
--data-urlencode 'oidcClientId=<clientId of IdP Registered App>' \
--data-urlencode 'oidcClientSecret=<clientSecret of IdP Registered App>' \
--data-urlencode 'redirectUrl=http://localhost:3366/*' \
--data-urlencode 'redirectUrl=http://localhost:3000/*' \
--data-urlencode 'tenant=ory.com' \
--data-urlencode 'product=demo' \
--data-urlencode 'name=demo-connection' \
--data-urlencode 'description=Demo OIDC connection'
```

--------------------------------

### Add SAML Connection

Source: https://boxyhq.com/docs/jackson/sso-flow

This API call sets up a SAML connection by providing IdP or SP metadata.

```APIDOC
## POST /api/v1/connections

### Description
Adds a new SAML connection to Ory Polis.

### Method
POST

### Endpoint
`http://localhost:5225/api/v1/connections`

### Parameters
#### Request Body
- **encodedRawMetadata** (string) - Required - Base64 encoding of the XML metadata from the Identity Provider. Either this or `metadataUrl` needs to be specified.
- **metadataUrl** (string) - Optional - URL containing the SAML metadata contents. Either this or `encodedRawMetadata` needs to be specified.
- **defaultRedirectUrl** (string) - Required - The redirect URL to use in the IdP login flow. Ory Polis will call this URL after completing an IdP login flow.
- **redirectUrl** (string) - Required - Allowed redirect URL. Repeat this field multiple times to allow multiple redirect URLs.
- **tenant** (string) - Required - A unique identifier for your customer's tenant.
- **product** (string) - Required - A unique identifier for the product your customer is using.
- **name** (string) - Required - A friendly name to identify the SAML connection.
- **description** (string) - Optional - A short description of the connection.

### Request Example
```bash
curl --location --request POST 'http://localhost:5225/api/v1/connections' \
--header 'Authorization: Api-Key <Ory Polis API Key>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'encodedRawMetadata=Base64(<IdP/SP metadata XML>)' \
--data-urlencode 'defaultRedirectUrl=http://localhost:3366/login/saml' \
--data-urlencode 'redirectUrl=http://localhost:3366/*' \
--data-urlencode 'redirectUrl=http://localhost:3000/*' \
--data-urlencode 'tenant=ory.com' \
--data-urlencode 'product=demo' \
--data-urlencode 'name=demo-connection' \
--data-urlencode 'description=Demo SAML connection'
```

### Response
#### Success Response (200)
- **clientID** (string) - The client ID for the connection.
- **clientSecret** (string) - The client secret for the connection.
- **idpMetadata.provider** (string) - The domain of your Identity Provider.
```

--------------------------------

### Verify Container Image with cosign

Source: https://boxyhq.com/docs/jackson/container-signing

Verify Ory container images using cosign and the fetched public key. This is supported for all versions >=1.6.0.

```bash
cosign verify --key cosign.pub ory/polis:<version>  

```

--------------------------------

### Get SAML/OIDC Connections

Source: https://boxyhq.com/docs/jackson/deploy/npm-library

Retrieve details of an existing SAML or OIDC Single Sign-On connection. You can query using tenant and product identifiers or by the connection's clientID.

```javascript
// Using tenant and product
await connection.getConnections({

  tenant: "ory",

  product: "your-app",

})

```

```javascript
// Using the client ID
await connection.getConnections({

  clientID: "<clientID of the SSO Connection to be retrieved>.",

})

```

```json
[
  {
    "defaultRedirectUrl": "https://your-app.com/sso/callback",

    "redirectUrl": ["https://your-app.com/*"],

    "tenant": "ory",

    "product": "your-app",

    "clientID": "...",

    "clientSecret": "...",

    "forceAuthn": false,

    "idpMetadata": {

      "sso": {

        "postUrl": "https://mocksaml.com/api/saml/sso",

        "redirectUrl": "https://mocksaml.com/api/saml/sso"

      },

      "slo": {},

      "entityID": "https://saml.example.com/entityid",

      "thumbprint": "d797f3829882233d3f01e49643f6a1195f242c94",

      "validTo": "Jul  1 21:46:38 3021 GMT",

      "loginType": "idp",

      "provider": "saml.example.com"

    },

    "certs": {

      "publicKey": "-----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----\r\n",

      "privateKey": "-----BEGIN RSA PRIVATE KEY----- ... -----END RSA PRIVATE KEY-----\r\n"

    }

  }
]

```

--------------------------------

### Create SAML Connection Request

Source: https://boxyhq.com/docs/jackson/deploy/npm-library

Use the `connection.createSAMLConnection` method to create a new SAML Single Sign-On connection. Provide tenant, product, raw SAML metadata, redirect URLs, and a default redirect URL.

```typescript
await connection.createSAMLConnection({
  tenant: "ory",
  product: "your-app",
  rawMetadata: "<raw-saml-metadata>", // Visit https://mocksaml.com to download Metadata
  redirectUrl: ["https://your-app.com/*"],
  defaultRedirectUrl: "https://your-app.com/sso/callback",
})
```

--------------------------------

### Get Directory by ID (Shell)

Source: https://boxyhq.com/docs/directory-sync/api-reference

Retrieve the details of a specific directory connection using a cURL command. Filters by the directory ID in the URL and requires an API key for authorization.

```shell
curl --request GET \
  --url 'http://localhost:5225/api/v1/directory-sync/58b5cd9dfaa39d47eb8f5f88631f9a629a232016' \
  --header 'Authorization: Api-Key secret' \
  --header 'Content-Type: application/json'
```