Back to top

API Documentation

SSO

A brokerage may decide to provide access to many other different applications for it’s users and agents and allow a single sign on onto their platforms, making Rechat a hub to all applications agents need.

Each application a brokerage provides to it’s users is called a “SSO Application” that can be managed using the following.

In order to launch an app, all clients have to do is to open up a new browser to sso_application.open_url.

Create an app

Create an app
POST/brands/:brand/sso_applications

The most important thing here is the authentication_type. SAML would be enabled for third party apps with SSO functionality. None for applications that can just be opened as a link and no sso is possible into them.

An optional roles array of brands_roles.id UUIDs restricts the initial assignment to those roles in the owning brand. Omit it or send null or [] to allow all roles.

Example URI

POST /brands/:brand/sso_applications
URI Parameters
HideShow
brand
string (required) Example: 7c27d4c4-bf95-4107-bebc-c39673004a9a
Request
HideShow
Body
{
  "name": "Test SSO Application",
  "authentication_type": "SAML",
  "acs_url": "https://samltest.id/saml/sp",
  "entity_id": "https://samltest.id/saml/sp",
  "start_url": null,
  "signed": null,
  "name_id": "null",
  "name_id_format": null,
  "mappings": null,
  "brands": [
    "7c27d4c4-bf95-4107-bebc-c39673004a9a"
  ]
}
Response  200
HideShow
Body
{
  "code": "OK",
  "data": {
    "id": "127f069c-5885-43ef-ae3a-5cfb8fef2e4b",
    "created_at": 1791656548.233768,
    "updated_at": 1791656548.233769,
    "deleted_at": null,
    "authentication_type": "SAML",
    "url": null,
    "acs_url": "https://samltest.id/saml/sp",
    "entity_id": "https://samltest.id/saml/sp",
    "start_url": null,
    "signed": null,
    "name": "Test SSO Application",
    "name_id": "null",
    "name_id_format": null,
    "mappings": null,
    "audience": null,
    "destination": null,
    "recipient": null,
    "order": 0,
    "issuer": "37dea40d-c443-4ffe-a3e7-22fc8b01ff7d",
    "extra": null,
    "type": "sso_application",
    "open_url": "http://localhost:3079/sso_applications/open?hash=jFzYu21eACj1jtjRFmdyB%2FxrgezPIhmLVGUPY9xaMyPEDyZ%2FG9WSvrZMmigYB2in0EyAaaVVmMFOTK1F7Bf5gh3LR6YbdcJZjk3pvhsofw8gzMjjinJueVs1faQQIOedXGOCTXNBhVZzE6EucRHyFmXLrMw0r3q%2FTrwhLTVBADGREvvq%2B5ekNfUVzCTq1DCTxD8NCiVO4AbbyGRw49k%2F8Twht%2BB1GkcB%2FzSlTls%3D",
    "metadata_url": "http://localhost:3079/sso_applications/127f069c-5885-43ef-ae3a-5cfb8fef2e4b.xml"
  }
}

Update an app

Update an app
PUT/brands/:brand/sso_applications/:id

Example URI

PUT /brands/:brand/sso_applications/:id
URI Parameters
HideShow
brand
string (required) Example: 7c27d4c4-bf95-4107-bebc-c39673004a9a
id
string (required) Example: 127f069c-5885-43ef-ae3a-5cfb8fef2e4b
Request
HideShow
Body
{
  "id": "127f069c-5885-43ef-ae3a-5cfb8fef2e4b",
  "created_at": 1791656548.233768,
  "updated_at": 1791656548.233769,
  "deleted_at": null,
  "authentication_type": "SAML",
  "url": null,
  "acs_url": "https://samltest.id/saml/sp",
  "entity_id": "https://samltest.id/saml/sp",
  "start_url": null,
  "signed": null,
  "name": "Updated Test SSO Application",
  "name_id": "null",
  "name_id_format": null,
  "mappings": null,
  "audience": null,
  "destination": null,
  "recipient": null,
  "order": 0,
  "issuer": "37dea40d-c443-4ffe-a3e7-22fc8b01ff7d",
  "extra": null,
  "type": "sso_application",
  "open_url": "http://localhost:3079/sso_applications/open?hash=jFzYu21eACj1jtjRFmdyB%2FxrgezPIhmLVGUPY9xaMyPEDyZ%2FG9WSvrZMmigYB2in0EyAaaVVmMFOTK1F7Bf5gh3LR6YbdcJZjk3pvhsofw8gzMjjinJueVs1faQQIOedXGOCTXNBhVZzE6EucRHyFmXLrMw0r3q%2FTrwhLTVBADGREvvq%2B5ekNfUVzCTq1DCTxD8NCiVO4AbbyGRw49k%2F8Twht%2BB1GkcB%2FzSlTls%3D",
  "metadata_url": "http://localhost:3079/sso_applications/127f069c-5885-43ef-ae3a-5cfb8fef2e4b.xml",
  "brands": [
    "7c27d4c4-bf95-4107-bebc-c39673004a9a"
  ]
}
Response  200
HideShow
Body
{
  "code": "OK",
  "data": {
    "id": "127f069c-5885-43ef-ae3a-5cfb8fef2e4b",
    "created_at": 1791656548.233768,
    "updated_at": 1791656548.233769,
    "deleted_at": null,
    "authentication_type": "SAML",
    "url": null,
    "acs_url": "https://samltest.id/saml/sp",
    "entity_id": "https://samltest.id/saml/sp",
    "start_url": null,
    "signed": null,
    "name": "Updated Test SSO Application",
    "name_id": "null",
    "name_id_format": null,
    "mappings": null,
    "audience": null,
    "destination": null,
    "recipient": null,
    "order": 0,
    "issuer": "37dea40d-c443-4ffe-a3e7-22fc8b01ff7d",
    "extra": null,
    "type": "sso_application",
    "open_url": "http://localhost:3079/sso_applications/open?hash=jFzYu21eACj1jtjRFmdyB%2FxrgezPIhmLVGUPY9xaMyPEDyZ%2FG9WSvrZMmigYB2in0EyAaaVVmMFOTK1F7Bf5gh3LR6YbdcJZjk3pvhsofw8gzMjjinJueVs1faQQIOedXGOCTXNBhVZzE6EucRHyFmXLrMw0r3q%2FTrwhLTVBADGREvvq%2B5ekNfUVzCTq1DCTxD8NCiVO4AbbyGRw49k%2F8Twht%2BB1GkcB%2Fj%2BlTls%3D",
    "metadata_url": "http://localhost:3079/sso_applications/127f069c-5885-43ef-ae3a-5cfb8fef2e4b.xml"
  }
}

Update app ordering

Update app ordering
PUT/brands/:brand/sso_applications/sort

It can handle multiple updates in one call.

Example URI

PUT /brands/:brand/sso_applications/sort
URI Parameters
HideShow
brand
string (required) Example: 7c27d4c4-bf95-4107-bebc-c39673004a9a
Request
HideShow
Body
[
  {
    "id": "d36aa776-ef4a-4988-9f06-6140785a5af6",
    "order": 27
  }
]
Response  200
HideShow
Body
{
  "code": "OK",
  "data": [
    {
      "id": "d36aa776-ef4a-4988-9f06-6140785a5af6",
      "order": 27
    }
  ],
  "info": {
    "count": 1,
    "total": 0
  }
}

Set Brands that are allowed to use this app

Set Brands that are allowed to use this app
PUT/brands/:brand/sso_applications/:id/brands

The body replaces the assigned brand list using the existing UUID array, with an optional roles array:

{"brands": ["<brand UUID>"], "roles": ["<role UUID 1>", "<role UUID 2>"]}

A nonempty roles array requires exactly one brand. Every role must be active and belong to that brand. Users with any selected role have access. Duplicate roles are stored once. Omit roles to preserve existing restrictions, or send roles: null or roles: [] to allow all roles. An empty brands array removes all assignments. The response format is unchanged.

Example URI

PUT /brands/:brand/sso_applications/:id/brands
URI Parameters
HideShow
brand
string (required) Example: 7c27d4c4-bf95-4107-bebc-c39673004a9a
id
string (required) Example: 127f069c-5885-43ef-ae3a-5cfb8fef2e4b
associations
string (required) Example: sso_application.brands
Request
HideShow
Body
{
  "brands": [
    "7c27d4c4-bf95-4107-bebc-c39673004a9a",
    "c85b09be-e60b-4bd1-87c3-461dbcd2feb1"
  ]
}
Response  200
HideShow
Body
{
  "code": "OK",
  "data": {
    "id": "127f069c-5885-43ef-ae3a-5cfb8fef2e4b",
    "created_at": 1791656548.233768,
    "updated_at": 1791656548.233769,
    "deleted_at": null,
    "authentication_type": "SAML",
    "url": null,
    "acs_url": "https://samltest.id/saml/sp",
    "entity_id": "https://samltest.id/saml/sp",
    "start_url": null,
    "signed": null,
    "name": "Updated Test SSO Application",
    "name_id": "null",
    "name_id_format": null,
    "mappings": null,
    "audience": null,
    "destination": null,
    "recipient": null,
    "order": 0,
    "issuer": "37dea40d-c443-4ffe-a3e7-22fc8b01ff7d",
    "extra": null,
    "type": "sso_application",
    "brands": [
      {
        "id": "7c27d4c4-bf95-4107-bebc-c39673004a9a",
        "created_at": 1791656547.78596,
        "updated_at": 1791656547.78596,
        "palette": null,
        "assets": null,
        "messages": null,
        "parent": null,
        "name": "Admin Brand Parent",
        "deleted_at": null,
        "training": false,
        "brand_type": "Brokerage",
        "parents": null,
        "type": "brand",
        "hostnames": null,
        "member_count": 1,
        "base_url": "https://irish.rechat.com"
      },
      {
        "id": "c85b09be-e60b-4bd1-87c3-461dbcd2feb1",
        "created_at": 1791656547.910124,
        "updated_at": 1791656547.910124,
        "palette": null,
        "assets": null,
        "messages": null,
        "parent": {
          "id": "7c27d4c4-bf95-4107-bebc-c39673004a9a",
          "created_at": 1791656547.78596,
          "updated_at": 1791656547.78596,
          "palette": null,
          "assets": null,
          "messages": null,
          "parent": null,
          "name": "Admin Brand Parent",
          "deleted_at": null,
          "training": false,
          "brand_type": "Brokerage",
          "parents": null,
          "type": "brand",
          "hostnames": null,
          "member_count": 1,
          "base_url": "https://irish.rechat.com"
        },
        "name": "Child Brand",
        "deleted_at": null,
        "training": false,
        "brand_type": "Team",
        "parents": [
          "7c27d4c4-bf95-4107-bebc-c39673004a9a"
        ],
        "type": "brand",
        "hostnames": null,
        "member_count": 0,
        "base_url": "https://irish.rechat.com"
      }
    ],
    "open_url": "http://localhost:3079/sso_applications/open?hash=jFzYu21eACj1jtjRFmdyB%2FxrgezPIhmLVGUPY9xaMyPEDyZ%2FG9WSvrZMmigYB2in0EyAaaVVmMFOTK1F7Bf5gh3LR6YbdcJZjk3pvhsofw8gzMjjinJueVs1faQQIOedXGOCTXNBhVZzE6EucRHyFmXLrMw0r3q%2FTrwhLTVBADGREvvq%2B5ekNfUVzCTq1DCTxD8NCiVO4AbbyGRw49k%2F8Twht%2BB1GkcH%2FjWlTls%3D",
    "metadata_url": "http://localhost:3079/sso_applications/127f069c-5885-43ef-ae3a-5cfb8fef2e4b.xml"
  }
}

Set Icon

Set Icon
PUT/brands/:brand/sso_applications/:id/icon

Example URI

PUT /brands/:brand/sso_applications/:id/icon
URI Parameters
HideShow
brand
string (required) Example: 7c27d4c4-bf95-4107-bebc-c39673004a9a
id
string (required) Example: 127f069c-5885-43ef-ae3a-5cfb8fef2e4b
associations
string (required) Example: sso_application.brands
Request
HideShow
Body
{
  "brands": [
    "7c27d4c4-bf95-4107-bebc-c39673004a9a",
    "c85b09be-e60b-4bd1-87c3-461dbcd2feb1"
  ]
}
Response  200
HideShow
Body
{
  "code": "OK",
  "data": {
    "id": "127f069c-5885-43ef-ae3a-5cfb8fef2e4b",
    "created_at": 1791656548.233768,
    "updated_at": 1791656548.233769,
    "deleted_at": null,
    "authentication_type": "SAML",
    "url": null,
    "acs_url": "https://samltest.id/saml/sp",
    "entity_id": "https://samltest.id/saml/sp",
    "start_url": null,
    "signed": null,
    "name": "Updated Test SSO Application",
    "name_id": "null",
    "name_id_format": null,
    "mappings": null,
    "audience": null,
    "destination": null,
    "recipient": null,
    "order": 0,
    "issuer": "37dea40d-c443-4ffe-a3e7-22fc8b01ff7d",
    "extra": null,
    "type": "sso_application",
    "brands": [
      {
        "id": "7c27d4c4-bf95-4107-bebc-c39673004a9a",
        "created_at": 1791656547.78596,
        "updated_at": 1791656547.78596,
        "palette": null,
        "assets": null,
        "messages": null,
        "parent": null,
        "name": "Admin Brand Parent",
        "deleted_at": null,
        "training": false,
        "brand_type": "Brokerage",
        "parents": null,
        "type": "brand",
        "hostnames": null,
        "member_count": 1,
        "base_url": "https://irish.rechat.com"
      },
      {
        "id": "c85b09be-e60b-4bd1-87c3-461dbcd2feb1",
        "created_at": 1791656547.910124,
        "updated_at": 1791656547.910124,
        "palette": null,
        "assets": null,
        "messages": null,
        "parent": {
          "id": "7c27d4c4-bf95-4107-bebc-c39673004a9a",
          "created_at": 1791656547.78596,
          "updated_at": 1791656547.78596,
          "palette": null,
          "assets": null,
          "messages": null,
          "parent": null,
          "name": "Admin Brand Parent",
          "deleted_at": null,
          "training": false,
          "brand_type": "Brokerage",
          "parents": null,
          "type": "brand",
          "hostnames": null,
          "member_count": 1,
          "base_url": "https://irish.rechat.com"
        },
        "name": "Child Brand",
        "deleted_at": null,
        "training": false,
        "brand_type": "Team",
        "parents": [
          "7c27d4c4-bf95-4107-bebc-c39673004a9a"
        ],
        "type": "brand",
        "hostnames": null,
        "member_count": 0,
        "base_url": "https://irish.rechat.com"
      }
    ],
    "open_url": "http://localhost:3079/sso_applications/open?hash=jFzYu21eACj1jtjRFmdyB%2FxrgezPIhmLVGUPY9xaMyPEDyZ%2FG9WSvrZMmigYB2in0EyAaaVVmMFOTK1F7Bf5gh3LR6YbdcJZjk3pvhsofw8gzMjjinJueVs1faQQIOedXGOCTXNBhVZzE6EucRHyFmXLrMw0r3q%2FTrwhLTVBADGREvvq%2B5ekNfUVzCTq1DCTxD8NCiVO4AbbyGRw49k%2F8Twht%2BB1GkcH%2FjWlTls%3D",
    "metadata_url": "http://localhost:3079/sso_applications/127f069c-5885-43ef-ae3a-5cfb8fef2e4b.xml"
  }
}

Get all available applications

Get all available applications
GET/brands/:brand/sso_applications

Example URI

GET /brands/:brand/sso_applications
URI Parameters
HideShow
brand
string (required) Example: 7c27d4c4-bf95-4107-bebc-c39673004a9a
Response  200
HideShow
Body
{
  "code": "OK",
  "data": [
    {
      "id": "127f069c-5885-43ef-ae3a-5cfb8fef2e4b",
      "created_at": 1791656548.233768,
      "updated_at": 1791656548.233769,
      "deleted_at": null,
      "authentication_type": "SAML",
      "url": null,
      "acs_url": "https://samltest.id/saml/sp",
      "entity_id": "https://samltest.id/saml/sp",
      "start_url": null,
      "signed": null,
      "name": "Updated Test SSO Application",
      "name_id": "null",
      "name_id_format": null,
      "mappings": null,
      "audience": null,
      "destination": null,
      "recipient": null,
      "order": 0,
      "issuer": "37dea40d-c443-4ffe-a3e7-22fc8b01ff7d",
      "extra": null,
      "type": "sso_application",
      "open_url": "http://localhost:3079/sso_applications/open?hash=jFzYu21eACj1jtjRFmdyB%2FxrgezPIhmLVGUPY9xaMyPEDyZ%2FG9WSvrZMmigYB2in0EyAaaVVmMFOTK1F7Bf5gh3LR6YbdcJZjk3pvhsofw8gzMjjinJueVs1faQQIOedXGOCTXNBhVZzE6EucRHyFmXLrMw0r3q%2FTrwhLTVBADGREvvq%2B5ekNfUVzCTq1DCTxD8NCiVO4AbbyGRw49k%2F8Twht%2BB1GkcH8jKlTls%3D",
      "metadata_url": "http://localhost:3079/sso_applications/127f069c-5885-43ef-ae3a-5cfb8fef2e4b.xml"
    },
    {
      "id": "d36aa776-ef4a-4988-9f06-6140785a5af6",
      "created_at": 1791656548.38597,
      "updated_at": 1791656548.385972,
      "deleted_at": null,
      "authentication_type": "SAML",
      "url": null,
      "acs_url": "https://samltest.id/saml/sp",
      "entity_id": "https://samltest.id/saml/sp",
      "start_url": null,
      "signed": null,
      "name": "Order Update Test SSO Application",
      "name_id": "null",
      "name_id_format": null,
      "mappings": null,
      "audience": null,
      "destination": null,
      "recipient": null,
      "order": 27,
      "issuer": "bf9f8b13-5a80-4a95-9b5f-29ff1e75eebb",
      "extra": null,
      "type": "sso_application",
      "open_url": "http://localhost:3079/sso_applications/open?hash=jFzYu21eACj1jtjRFmdyB%2FxrgezPIhmLVGUPY9xaMyPEDyZ%2FG9WSvrZMmigYB2in0EyAaaVVzcBPS%2FxE4kL50kPHE6Ybf58HjhXqvUwofF1ynse92nVpfQlhfaQQIOedXGOCTXNBhVZzE6EucRHyFmXLrMw0r3q%2FTrwhLTVBADGREvvq%2B5ekNfUVzCTq1DCTxD8NCiVO4AbbyGRw49k%2F8Twht%2BB1GkcH8jOlTls%3D",
      "metadata_url": "http://localhost:3079/sso_applications/d36aa776-ef4a-4988-9f06-6140785a5af6.xml"
    }
  ],
  "info": {
    "count": 2,
    "total": 0
  }
}

Delete an app

Delete an app
DELETE/brands/:brand/sso_applications/:id

Example URI

DELETE /brands/:brand/sso_applications/:id
URI Parameters
HideShow
brand
string (required) Example: 7c27d4c4-bf95-4107-bebc-c39673004a9a
id
string (required) Example: 127f069c-5885-43ef-ae3a-5cfb8fef2e4b
Request
HideShow
Body
{
  "id": "127f069c-5885-43ef-ae3a-5cfb8fef2e4b",
  "created_at": 1791656548.233768,
  "updated_at": 1791656548.233769,
  "deleted_at": null,
  "authentication_type": "SAML",
  "url": null,
  "acs_url": "https://samltest.id/saml/sp",
  "entity_id": "https://samltest.id/saml/sp",
  "start_url": null,
  "signed": null,
  "name": "Updated Test SSO Application",
  "name_id": "null",
  "name_id_format": null,
  "mappings": null,
  "audience": null,
  "destination": null,
  "recipient": null,
  "order": 0,
  "issuer": "37dea40d-c443-4ffe-a3e7-22fc8b01ff7d",
  "extra": null,
  "type": "sso_application",
  "open_url": "http://localhost:3079/sso_applications/open?hash=jFzYu21eACj1jtjRFmdyB%2FxrgezPIhmLVGUPY9xaMyPEDyZ%2FG9WSvrZMmigYB2in0EyAaaVVmMFOTK1F7Bf5gh3LR6YbdcJZjk3pvhsofw8gzMjjinJueVs1faQQIOedXGOCTXNBhVZzE6EucRHyFmXLrMw0r3q%2FTrwhLTVBADGREvvq%2B5ekNfUVzCTq1DCTxD8NCiVO4AbbyGRw49k%2F8Twht%2BB1GkcB%2FzSlTls%3D",
  "metadata_url": "http://localhost:3079/sso_applications/127f069c-5885-43ef-ae3a-5cfb8fef2e4b.xml",
  "brands": [
    "7c27d4c4-bf95-4107-bebc-c39673004a9a"
  ]
}
Response  200
HideShow
Body
{
  "code": "OK",
  "data": {
    "id": "127f069c-5885-43ef-ae3a-5cfb8fef2e4b",
    "created_at": 1791656548.233768,
    "updated_at": 1791656548.233769,
    "deleted_at": null,
    "authentication_type": "SAML",
    "url": null,
    "acs_url": "https://samltest.id/saml/sp",
    "entity_id": "https://samltest.id/saml/sp",
    "start_url": null,
    "signed": null,
    "name": "Updated Test SSO Application",
    "name_id": "null",
    "name_id_format": null,
    "mappings": null,
    "audience": null,
    "destination": null,
    "recipient": null,
    "order": 0,
    "issuer": "37dea40d-c443-4ffe-a3e7-22fc8b01ff7d",
    "extra": null,
    "type": "sso_application",
    "open_url": "http://localhost:3079/sso_applications/open?hash=jFzYu21eACj1jtjRFmdyB%2FxrgezPIhmLVGUPY9xaMyPEDyZ%2FG9WSvrZMmigYB2in0EyAaaVVmMFOTK1F7Bf5gh3LR6YbdcJZjk3pvhsofw8gzMjjinJueVs1faQQIOedXGOCTXNBhVZzE6EucRHyFmXLrMw0r3q%2FTrwhLTVBADGREvvq%2B5ekNfUVzCTq1DCTxD8NCiVO4AbbyGRw49k%2F8Twht%2BB1GkcB%2Fj%2BlTls%3D",
    "metadata_url": "http://localhost:3079/sso_applications/127f069c-5885-43ef-ae3a-5cfb8fef2e4b.xml"
  }
}

Generated by aglio on 10 Oct 2026