{
"openapi": "3.0.3",
"info": {
"title": "Organizations",
"description": "In business-to-business (B2B) use cases, organizations represent your business customers and partners. You can manage these organizations, and delegate access so they can manage their own membership. Using member APIs, organizations can manage the profiles of their users, control which apps they can access, and federate login to those apps using their own SAML-based identity providers.",
"version": ""
},
"servers": [
{
"url": "https://api.sbx.transmitsecurity.io/cis",
"description": "Sandbox environment"
},
{
"url": "https://api.transmitsecurity.io/cis",
"description": "Production environment (US)"
},
{
"url": "https://api.eu.transmitsecurity.io/cis",
"description": "Production environment (EU)"
},
{
"url": "https://api.ca.transmitsecurity.io/cis",
"description": "Production environment (CA)"
},
{
"url": "https://api.au.transmitsecurity.io/cis",
"description": "Production environment (AU)"
}
],
"security": [],
"paths": {
"/v1/organizations": {
"post": {
"operationId": "createOrganization",
"summary": "Create organization",
"description": "Create an organization that represents your business customer or partner. This should be called from the backend, using an admin access token (generated by a management app).
**Required permissions**: `organizations:create`, `orgs:create`.",
"parameters": [],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiCreateOrganizationInput"
}
}
}
},
"responses": {
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"title": "ApiCreatedResponse-createOrganization",
"type": "object",
"required": [
"result"
],
"description": "Organization created",
"properties": {
"result": {
"$ref": "#/components/schemas/ApiOrganization"
}
}
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequestHttpError"
}
}
}
},
"409": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IdentifierIsTakenHttpError"
}
}
}
}
},
"security": [
{
"AdminAccessToken": []
}
]
},
"get": {
"operationId": "getAllOrganizations",
"summary": "Get organizations",
"description": "Retrieve a list of all organizations. This should be called from the backend, using an admin access token (generated by a management app).
**Required permissions**: `organizations:read`, `orgs:read`, `organizations:list`, `orgs:list`.",
"parameters": [
{
"name": "name",
"required": false,
"in": "query",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"title": "ApiOkResponse-getAllOrganizations",
"type": "object",
"required": [
"result"
],
"description": "List of organizations",
"properties": {
"result": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiOrganization"
}
}
}
}
}
}
}
},
"security": [
{
"AdminAccessToken": []
}
]
}
},
"/v1/organizations/{organization_id}": {
"get": {
"operationId": "getOrganization",
"summary": "Get organization by ID",
"description": "Retrieve an organization by ID. This should be called from the backend, using an admin access token (generated by a management app).
**Required permissions**: `organizations:read`, `orgs:read`.",
"parameters": [
{
"name": "organization_id",
"required": true,
"in": "path",
"description": "ID of the organization to retrieve",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"title": "ApiOkResponse-getOrganization",
"type": "object",
"required": [
"result"
],
"description": "Organization information",
"properties": {
"result": {
"$ref": "#/components/schemas/ApiOrganization"
}
}
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotFoundHttpError"
}
}
}
}
},
"security": [
{
"AdminAccessToken": []
}
]
},
"put": {
"operationId": "updateOrganization",
"summary": "Update organization",
"description": "Update an organization's basic configuration. This should be called from the backend, using an admin access token (generated by a management app).
**Required permissions**: `organizations:edit`, `orgs:edit`.",
"parameters": [
{
"name": "organization_id",
"required": true,
"in": "path",
"description": "ID of the organization to update",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiUpdateOrganizationInput"
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"title": "ApiOkResponse-updateOrganization",
"type": "object",
"required": [
"result"
],
"description": "Updated organization",
"properties": {
"result": {
"$ref": "#/components/schemas/ApiOrganization"
}
}
}
}
}
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequestHttpError"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotFoundHttpError"
}
}
}
}
},
"security": [
{
"AdminAccessToken": []
}
]
},
"delete": {
"operationId": "deleteOrganization",
"summary": "Delete organization",
"description": "Delete an organization. This should be called from the backend, using an admin access token (generated by a management app).
**Required permissions**: `organizations:delete`, `orgs:delete`.",
"parameters": [
{
"name": "organization_id",
"required": true,
"in": "path",
"description": "The ID of the organization that should be deleted",
"schema": {
"type": "string"
}
}
],
"responses": {
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequestHttpError"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotFoundHttpError"
}
}
}
}
},
"security": [
{
"AdminAccessToken": []
}
]
}
},
"/v1/organizations/name/{organization_name}": {
"get": {
"operationId": "getOrganizationByName",
"summary": "Get organization by name",
"description": "Retrieve an organization by name. This should be called from the backend, using an admin access token (generated by a management app).
**Required permissions**: `organizations:read`, `orgs:read`.",
"parameters": [
{
"name": "organization_name",
"required": true,
"in": "path",
"description": "Name of the organization to retrieve",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"title": "ApiOkResponse-getOrganizationByName",
"type": "object",
"required": [
"result"
],
"description": "Organization information",
"properties": {
"result": {
"$ref": "#/components/schemas/ApiOrganization"
}
}
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotFoundHttpError"
}
}
}
}
},
"security": [
{
"AdminAccessToken": []
}
]
}
},
"/v1/organizations/{organization_id}/apps": {
"put": {
"operationId": "addAppsToOrganization",
"summary": "Add apps to organization",
"description": "Add apps to the organization so its members can access them. If the organization already has apps, this can be used to add additional ones. This should be called from the backend, using an admin access token (generated by a management app).
**Required permissions**: `organizations:edit`, `orgs:edit`.",
"parameters": [
{
"name": "organization_id",
"required": true,
"in": "path",
"description": "The ID of the organization that should be updated",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiAppIds"
}
}
}
},
"responses": {
"204": {
"description": ""
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequestHttpError"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotFoundHttpError"
}
}
}
}
},
"security": [
{
"AdminAccessToken": []
}
]
},
"delete": {
"operationId": "removeAppsFromOrganization",
"summary": "Remove apps from organization",
"description": "Remove apps from the organization so its members cannot access them. This should be called from the backend, using an admin access token (generated by a management app).
**Required permissions**: `organizations:edit`, `orgs:edit`.",
"parameters": [
{
"name": "organization_id",
"required": true,
"in": "path",
"description": "The ID of the organization that should be updated",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiAppIds"
}
}
}
},
"responses": {
"204": {
"description": ""
},
"400": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequestHttpError"
}
}
}
},
"404": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotFoundHttpError"
}
}
}
}
},
"security": [
{
"AdminAccessToken": []
}
]
}
},
"/v1/organizations/{organization_id}/logo": {
"post": {
"operationId": "uploadLogo",
"summary": "Upload organization logo",
"description": "Upload the organization logo and update the logo URL in the database. This should be called from the backend, using an admin access token (generated by a management app).
**Required permissions**: `organizations:edit`, `orgs:edit`.",
"parameters": [
{
"name": "organization_id",
"required": true,
"in": "path",
"description": "ID of the organization to upload the logo for",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"description": "Logo image",
"content": {
"multipart/form-data": {
"schema": {
"$ref": "#/components/schemas/LogoUploadDto"
}
}
}
},
"responses": {
"202": {
"description": ""
}
},
"security": [
{
"AdminAccessToken": []
}
]
}
},
"/v1/organizations/{organization_id}/applications/{app_id}/managed-organizations": {
"post": {
"operationId": "createManagedOrganization",
"summary": "Create managed organization",
"description": "Create a managed organization in context of a specific app. This should be called from the backend, using an admin access token (generated by a management app) or an organization admin access token.
**Required permissions**: `organizations:create`, `orgs:create`.",
"parameters": [
{
"name": "organization_id",
"required": true,
"in": "path",
"description": "The ID of the organization that creates the managed organization",
"schema": {
"type": "string"
}
},
{
"name": "app_id",
"required": true,
"in": "path",
"description": "ID of application",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiCreateManagedOrganizationInput"
}
}
}
},
"responses": {
"201": {
"description": "",
"content": {
"application/json": {
"schema": {
"title": "ApiCreatedResponse-createManagedOrganization",
"type": "object",
"required": [
"result"
],
"description": "Managed organization created",
"properties": {
"result": {
"$ref": "#/components/schemas/ApiOrganization"
}
}
}
}
}
},
"409": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IdentifierIsTakenHttpError"
}
}
}
}
},
"security": [
{
"AdminAccessToken": []
}
]
}
},
"/v1/applications/{app_id}/organizations/{organization_id}/role-groups/set": {
"post": {
"operationId": "setAssignedRoleGroups",
"summary": "Set org's role groups",
"description": "Update the role groups of the organization for a specific application, which will replace any existing role groups for the organization. These role groups must first be created for the application. Once added to the organization, roles that belong to these role groups can be assigned to members of the organization to control their access to the application.
**Required permissions**: `organizations:edit`, `orgs:edit`.",
"parameters": [
{
"name": "app_id",
"required": true,
"in": "path",
"description": "ID of the application to set the roles to",
"schema": {
"type": "string"
}
},
{
"name": "organization_id",
"required": true,
"in": "path",
"description": "ID of the organization to set the roles to",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiRoleGroupIds"
}
}
}
},
"responses": {
"202": {
"description": ""
}
},
"security": [
{
"AdminAccessToken": []
}
]
}
},
"/v1/applications/{app_id}/organizations/{organization_id}/role-groups": {
"get": {
"operationId": "getAssignedRoleGroups",
"summary": "Get org's role groups",
"description": "Retrieves all role groups that were added to the organization for a specific application. Roles that belong to these role groups can be assigned to members of the organization to control their access to the application.
**Required permissions**: `organizations:read`, `orgs:read`.",
"parameters": [
{
"name": "app_id",
"required": true,
"in": "path",
"description": "ID of the application to assign the roles to",
"schema": {
"type": "string"
}
},
{
"name": "organization_id",
"required": true,
"in": "path",
"description": "ID of the organization to assign the roles to",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"title": "ApiOkResponse-getAssignedRoleGroups",
"type": "object",
"required": [
"result"
],
"description": "",
"properties": {
"result": {
"$ref": "#/components/schemas/RoleGroupsAndDefaultOrgRolesDto"
}
}
}
}
}
}
},
"security": [
{
"AdminAccessToken": []
}
]
}
}
},
"components": {
"schemas": {
"ApiCreateOrganizationInput": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the organization"
},
"domain": {
"type": "string",
"description": "Domain of the organization",
"deprecated": true
},
"domains": {
"description": "Domains of the organization",
"type": "array",
"items": {
"type": "string"
}
},
"app_ids": {
"description": "A list of applications the organization can access",
"type": "array",
"items": {
"type": "string"
}
},
"enabled": {
"type": "boolean",
"description": "Indicates if the organization is currently enabled"
},
"alias_name": {
"type": "string",
"description": "Alias name of the organization"
}
},
"required": [
"name",
"domain",
"domains",
"app_ids"
]
},
"BadRequestHttpError": {
"type": "object",
"properties": {
"message": {
"example": "Bad request",
"type": "array",
"items": {
"type": "string"
}
},
"error_code": {
"type": "number",
"example": 400
}
},
"required": [
"message",
"error_code"
]
},
"IdentifierIsTakenHttpError": {
"type": "object",
"properties": {
"message": {
"type": "string"
},
"error_code": {
"type": "number"
}
},
"required": [
"message",
"error_code"
]
},
"ApiOrganization": {
"type": "object",
"properties": {
"organization_id": {
"type": "string",
"description": "ID of the organization"
},
"app_ids": {
"description": "A list of applications the organization can access",
"type": "array",
"items": {
"type": "string"
}
},
"name": {
"type": "string",
"description": "Name of the organization"
},
"domain": {
"type": "string",
"description": "Domain of the organization",
"deprecated": true
},
"domains": {
"description": "Domains of the organization",
"type": "array",
"items": {
"type": "string"
}
},
"created_at": {
"type": "number",
"description": "Date the organization was created in the tenant"
},
"updated_at": {
"type": "number",
"description": "Date the organization was last updated"
},
"enabled": {
"type": "boolean",
"description": "Indicates if the organization is currently enabled"
},
"managed_organizations_by_app": {
"type": "object",
"description": "Mapping of app IDs to managed organization IDs assigned to this app",
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
}
},
"managing_organization_id": {
"type": "string",
"description": "ID of the managing organization"
},
"logo_url": {
"type": "string",
"description": "The URL of the organization's logo"
},
"alias_name": {
"type": "string",
"description": "Alias name of the organization"
}
},
"required": [
"organization_id",
"app_ids",
"name",
"domain",
"enabled"
]
},
"NotFoundHttpError": {
"type": "object",
"properties": {
"message": {
"type": "string"
},
"error_code": {
"type": "number",
"example": 404
}
},
"required": [
"message",
"error_code"
]
},
"ApiUpdateOrganizationInput": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the organization"
},
"domain": {
"type": "string",
"description": "Domain of the organization",
"deprecated": true
},
"domains": {
"description": "Domains of the organization",
"type": "array",
"items": {
"type": "string"
}
},
"enabled": {
"type": "boolean",
"description": "Indicates if the organization is currently enabled"
},
"alias_name": {
"type": "string",
"description": "Alias name of the organization"
}
}
},
"ApiAppIds": {
"type": "object",
"properties": {
"app_ids": {
"description": "A list of applications to add the organization to",
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"app_ids"
]
},
"LogoUploadDto": {
"type": "object",
"properties": {
"logo": {
"type": "string",
"format": "binary"
}
},
"required": [
"logo"
]
},
"ApiCreateManagedOrganizationInput": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the organization"
},
"domain": {
"type": "string",
"description": "Domain of the organization",
"deprecated": true
},
"domains": {
"description": "Domains of the organization",
"type": "array",
"items": {
"type": "string"
}
},
"enabled": {
"type": "boolean",
"description": "Indicates if the organization is currently enabled"
},
"alias_name": {
"type": "string",
"description": "Alias name of the managed organization"
}
},
"required": [
"name",
"domain",
"domains"
]
},
"ApiRoleGroupIds": {
"type": "object",
"properties": {
"role_group_ids": {
"description": "Role group ids",
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"role_group_ids"
]
},
"RoleGroupsAndDefaultOrgRolesDto": {
"type": "object",
"properties": {
"role_groups": {
"description": "Role groups",
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiRoleGroup"
}
},
"default_organization_roles": {
"description": "Default organization roles",
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiRole"
}
}
},
"required": [
"role_groups",
"default_organization_roles"
]
},
"ApiRoleGroup": {
"type": "object",
"properties": {
"group_id": {
"type": "string",
"description": "Group ID"
},
"name": {
"type": "string",
"description": "Group name"
},
"description": {
"type": "string",
"description": "Group description"
},
"roles": {
"description": "Group's roles",
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiRole"
}
},
"display_name": {
"type": "string",
"description": "Role group's display name"
}
},
"required": [
"group_id",
"name",
"roles"
]
},
"ApiRole": {
"type": "object",
"properties": {
"role_id": {
"type": "string",
"description": "Role ID"
},
"role_name": {
"type": "string",
"description": "Role name"
},
"permissions": {
"description": "Role permissions",
"type": "array",
"items": {
"type": "string"
}
},
"app_id": {
"type": "string",
"description": "Role's app id"
},
"description": {
"type": "string",
"description": "Role's description"
},
"display_name": {
"type": "string",
"description": "Role's display name"
}
},
"required": [
"role_id",
"role_name"
]
}
},
"securitySchemes": {
"bearer": {
"scheme": "bearer",
"bearerFormat": "JWT",
"type": "http"
},
"UserAccessToken": {
"type": "http",
"description": "A token returned upon end-user authentication, which provides access to resources and data for the user and app for which it was generated",
"scheme": "bearer",
"bearerFormat": "JWT"
},
"AdminAccessToken": {
"type": "oauth2",
"flows": {
"clientCredentials": {
"tokenUrl": "/oidc/token",
"scopes": {}
}
},
"description": "A token generated by a management application using the [token endpoint](/openapi/token.openapi/other/getaccesstoken). It provides access to all resources for the tenant and its apps"
},
"ClientAccessToken": {
"type": "oauth2",
"flows": {
"clientCredentials": {
"tokenUrl": "/oidc/token",
"scopes": {}
}
},
"description": "A token generated by an end-user application using the [token endpoint](/openapi/token.openapi/other/getaccesstoken). It provides access to resources and data on the tenant level or associated with the specific application (but not other apps in the tenant)"
},
"OrgAdminAccessToken": {
"type": "oauth2",
"flows": {
"clientCredentials": {
"tokenUrl": "/oidc/token",
"scopes": {}
}
},
"description": "A token returned upon B2B authentication for a user that has the organizationAdmin or organizationCreator role."
}
}
}
}