Organizations

Multi-tenant organization management, member invitations, and settings.

POST/api/v1/organizationsCreate OrganizationBearer Token▾

Create a new organization. The authenticated user becomes the first super-admin of the org.

Request Body

Name	Type	Required	Description
`name`	string	Required	Display name of the organization.e.g. `Acme Corp`
`slug`	string	Optional	URL-safe identifier. Auto-generated from name if omitted.e.g. `acme-corp`
`domain`	string	Optional	Primary domain associated with the organization.e.g. `acme.com`
`logoUrl`	string	Optional	Public URL of the organization logo.e.g. `https://cdn.acme.com/logo.png`
`primaryColor`	string	Optional	Brand hex color used in hosted UI.e.g. `#0057FF`
`allowedDomains`	string[]	Optional	List of email domains whose users may self-join.e.g. `["acme.com","acme.io"]`

Response Fields

Name	Type	Required	Description
`id`	string (UUID)	Optional	Organization unique identifier.e.g. `org_01HZ3K8VPNQ4RJXEMYVWCT9BS1`
`name`	string	Optional	Display name.e.g. `Acme Corp`
`slug`	string	Optional	URL-safe identifier.e.g. `acme-corp`
`domain`	string \| null	Optional	Primary domain.e.g. `acme.com`
`plan`	string	Optional	Subscription plan.e.g. `FREE`
`status`	string	Optional	Organization status.e.g. `ACTIVE`
`logoUrl`	string \| null	Optional	Logo URL.e.g. `https://cdn.acme.com/logo.png`
`primaryColor`	string \| null	Optional	Brand hex color.e.g. `#0057FF`
`allowedDomains`	string[]	Optional	Self-join allowed domains.e.g. `["acme.com"]`
`maxMembers`	number	Optional	Maximum member seats.e.g. `50`
`maxApplications`	number	Optional	Maximum application count.e.g. `10`
`createdAt`	string (ISO 8601)	Optional	Creation timestamp.e.g. `2024-01-15T10:30:00.000Z`
`updatedAt`	string (ISO 8601)	Optional	Last update timestamp.e.g. `2024-01-15T10:30:00.000Z`

Response Example

{
  "id": "org_01HZ3K8VPNQ4RJXEMYVWCT9BS1",
  "name": "Acme Corp",
  "slug": "acme-corp",
  "domain": "acme.com",
  "plan": "FREE",
  "status": "ACTIVE",
  "logoUrl": "https://cdn.acme.com/logo.png",
  "primaryColor": "#0057FF",
  "allowedDomains": [
    "acme.com"
  ],
  "maxMembers": 50,
  "maxApplications": 10,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}

Code Examples

curl -X POST https://api.sutraid.com/api/v1/organizations \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "slug": "acme-corp",
    "domain": "acme.com",
    "logoUrl": "https://cdn.acme.com/logo.png",
    "primaryColor": "#0057FF",
    "allowedDomains": ["acme.com", "acme.io"]
  }'

GET/api/v1/organizationsList OrganizationsBearer Token▾

Retrieve all organizations the authenticated user belongs to.

Response Fields

Name	Type	Required	Description
`[]`	Organization[]	Optional	Array of organization records the user is a member of.

Response Example

{
  "data": [
    {
      "id": "org_01HZ3K8VPNQ4RJXEMYVWCT9BS1",
      "name": "Acme Corp",
      "slug": "acme-corp",
      "domain": "acme.com",
      "plan": "FREE",
      "status": "ACTIVE",
      "logoUrl": "https://cdn.acme.com/logo.png",
      "primaryColor": "#0057FF",
      "allowedDomains": [
        "acme.com"
      ],
      "maxMembers": 50,
      "maxApplications": 10,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    }
  ]
}

Code Examples

curl -X GET https://api.sutraid.com/api/v1/organizations \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..."

GET/api/v1/organizations/:orgIdGet OrganizationBearer Token▾

Retrieve details for a specific organization by its ID.

Parameters

Name	Type	Required	Description
`orgId`	string (UUID)	Required	The unique identifier of the organization.e.g. `org_01HZ3K8VPNQ4RJXEMYVWCT9BS1`

Response Fields

Name	Type	Required	Description
`id`	string (UUID)	Optional	Organization unique identifier.e.g. `org_01HZ3K8VPNQ4RJXEMYVWCT9BS1`
`name`	string	Optional	Display name.e.g. `Acme Corp`
`slug`	string	Optional	URL-safe identifier.e.g. `acme-corp`
`domain`	string \| null	Optional	Primary domain.e.g. `acme.com`
`plan`	string	Optional	Subscription plan.e.g. `FREE`
`status`	string	Optional	Organization status.e.g. `ACTIVE`
`createdAt`	string (ISO 8601)	Optional	Creation timestamp.e.g. `2024-01-15T10:30:00.000Z`
`updatedAt`	string (ISO 8601)	Optional	Last update timestamp.e.g. `2024-01-15T10:30:00.000Z`

Response Example

{
  "id": "org_01HZ3K8VPNQ4RJXEMYVWCT9BS1",
  "name": "Acme Corp",
  "slug": "acme-corp",
  "domain": "acme.com",
  "plan": "FREE",
  "status": "ACTIVE",
  "logoUrl": "https://cdn.acme.com/logo.png",
  "primaryColor": "#0057FF",
  "allowedDomains": [
    "acme.com"
  ],
  "maxMembers": 50,
  "maxApplications": 10,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}

Code Examples

curl -X GET https://api.sutraid.com/api/v1/organizations/org_01HZ3K8VPNQ4RJXEMYVWCT9BS1 \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..."

PUT/api/v1/organizations/:orgIdUpdate OrganizationBearer Token▾

Update organization details. All body fields are optional; only provided fields are updated.

Parameters

Name	Type	Required	Description
`orgId`	string (UUID)	Required	The unique identifier of the organization to update.e.g. `org_01HZ3K8VPNQ4RJXEMYVWCT9BS1`

Request Body

Name	Type	Required	Description
`name`	string	Optional	New display name.e.g. `Acme Corporation`
`slug`	string	Optional	New URL-safe identifier.e.g. `acme-corporation`
`domain`	string	Optional	New primary domain.e.g. `acmecorp.com`
`logoUrl`	string	Optional	New logo URL.e.g. `https://cdn.acme.com/logo-v2.png`
`primaryColor`	string	Optional	New brand hex color.e.g. `#FF5700`
`allowedDomains`	string[]	Optional	Updated self-join domain list.e.g. `["acmecorp.com"]`
`plan`	string	Optional	Subscription plan.e.g. `PRO`
`status`	string	Optional	Organization status.e.g. `ACTIVE`
`maxMembers`	number	Optional	Maximum member seats.e.g. `100`
`maxApplications`	number	Optional	Maximum application count.e.g. `20`

Response Fields

Name	Type	Required	Description
`id`	string (UUID)	Optional	Organization unique identifier.
`name`	string	Optional	Updated display name.e.g. `Acme Corporation`
`updatedAt`	string (ISO 8601)	Optional	Timestamp of the update.

Response Example

{
  "id": "org_01HZ3K8VPNQ4RJXEMYVWCT9BS1",
  "name": "Acme Corporation",
  "slug": "acme-corporation",
  "domain": "acmecorp.com",
  "plan": "PRO",
  "status": "ACTIVE",
  "logoUrl": "https://cdn.acme.com/logo-v2.png",
  "primaryColor": "#FF5700",
  "allowedDomains": [
    "acmecorp.com"
  ],
  "maxMembers": 100,
  "maxApplications": 20,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-06-01T08:00:00.000Z"
}

Code Examples

curl -X PUT https://api.sutraid.com/api/v1/organizations/org_01HZ3K8VPNQ4RJXEMYVWCT9BS1 \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation",
    "slug": "acme-corporation",
    "primaryColor": "#FF5700",
    "maxMembers": 100
  }'

DELETE/api/v1/organizations/:orgIdDelete OrganizationBearer Token▾

Permanently delete an organization and all associated data. This action is irreversible.

Parameters

Name	Type	Required	Description
`orgId`	string (UUID)	Required	The unique identifier of the organization to delete.e.g. `org_01HZ3K8VPNQ4RJXEMYVWCT9BS1`

Response Fields

Name	Type	Required	Description
`message`	string	Optional	Confirmation message.e.g. `Organization deleted`

Response Example

{
  "message": "Organization deleted"
}

Code Examples

curl -X DELETE https://api.sutraid.com/api/v1/organizations/org_01HZ3K8VPNQ4RJXEMYVWCT9BS1 \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..."

POST/api/v1/organizations/:orgId/members/inviteInvite MemberBearer Token▾

Send an invitation email to a user to join the organization with a specified role.

Parameters

Name	Type	Required	Description
`orgId`	string (UUID)	Required	The organization to invite the user into.e.g. `org_01HZ3K8VPNQ4RJXEMYVWCT9BS1`

Request Body

Name	Type	Required	Description
`email`	string	Required	Email address of the person to invite.e.g. `jane.doe@acme.com`
`role`	OrgRole	Required	Role to assign to the invited member.e.g. `ORG_ADMIN` `SUPER_ADMINORG_ADMINAPP_ADMINUSER_ADMINGROUP_MEMBERSHIP_ADMINHELP_DESK_ADMINMOBILE_ADMINREAD_ONLY_ADMINREPORT_ADMINAPI_ACCESS_MANAGEMENT_ADMIN`

Response Fields

Name	Type	Required	Description
`id`	string (UUID)	Optional	Invitation record identifier.
`email`	string	Optional	Invited email address.e.g. `jane.doe@acme.com`
`role`	OrgRole	Optional	Assigned role.e.g. `ORG_ADMIN`
`status`	string	Optional	Invitation status.e.g. `PENDING`
`expiresAt`	string (ISO 8601)	Optional	Invitation expiry timestamp.

Response Example

{
  "id": "inv_01HZ4M9XPQR5SKTBZCYF2DN3W7",
  "email": "jane.doe@acme.com",
  "role": "ORG_ADMIN",
  "status": "PENDING",
  "organizationId": "org_01HZ3K8VPNQ4RJXEMYVWCT9BS1",
  "expiresAt": "2024-01-22T10:30:00.000Z",
  "createdAt": "2024-01-15T10:30:00.000Z"
}

Code Examples

curl -X POST https://api.sutraid.com/api/v1/organizations/org_01HZ3K8VPNQ4RJXEMYVWCT9BS1/members/invite \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane.doe@acme.com",
    "role": "ORG_ADMIN"
  }'

PUT/api/v1/organizations/:orgId/members/:memberId/roleUpdate Member RoleBearer Token▾

Change the role of an existing organization member.

Parameters

Name	Type	Required	Description
`orgId`	string (UUID)	Required	The organization identifier.e.g. `org_01HZ3K8VPNQ4RJXEMYVWCT9BS1`
`memberId`	string (UUID)	Required	The member identifier to update.e.g. `mem_01HZ5P2WQRS6TLUCADYG3EN4X8`

Request Body

Name	Type	Required	Description
`role`	OrgRole	Required	The new role to assign to the member.e.g. `APP_ADMIN` `SUPER_ADMINORG_ADMINAPP_ADMINUSER_ADMINGROUP_MEMBERSHIP_ADMINHELP_DESK_ADMINMOBILE_ADMINREAD_ONLY_ADMINREPORT_ADMINAPI_ACCESS_MANAGEMENT_ADMIN`

Response Fields

Name	Type	Required	Description
`id`	string (UUID)	Optional	Member record identifier.
`userId`	string (UUID)	Optional	User identifier.
`organizationId`	string (UUID)	Optional	Organization identifier.
`role`	OrgRole	Optional	Updated role.e.g. `APP_ADMIN`
`updatedAt`	string (ISO 8601)	Optional	Timestamp of the update.

Response Example

{
  "id": "mem_01HZ5P2WQRS6TLUCADYG3EN4X8",
  "userId": "usr_01HY9K7MNPQ3RJCEBXVWDT8GS2",
  "organizationId": "org_01HZ3K8VPNQ4RJXEMYVWCT9BS1",
  "role": "APP_ADMIN",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-06-01T09:15:00.000Z"
}

Code Examples

curl -X PUT https://api.sutraid.com/api/v1/organizations/org_01HZ3K8VPNQ4RJXEMYVWCT9BS1/members/mem_01HZ5P2WQRS6TLUCADYG3EN4X8/role \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..." \
  -H "Content-Type: application/json" \
  -d '{ "role": "APP_ADMIN" }'

DELETE/api/v1/organizations/:orgId/members/:memberIdRemove MemberBearer Token▾

Remove a member from the organization. The user account itself is not deleted.

Parameters

Name	Type	Required	Description
`orgId`	string (UUID)	Required	The organization identifier.e.g. `org_01HZ3K8VPNQ4RJXEMYVWCT9BS1`
`memberId`	string (UUID)	Required	The member identifier to remove.e.g. `mem_01HZ5P2WQRS6TLUCADYG3EN4X8`

Response Fields

Name	Type	Required	Description
`message`	string	Optional	Confirmation message.e.g. `Member removed`

Response Example

{
  "message": "Member removed"
}

Code Examples

curl -X DELETE https://api.sutraid.com/api/v1/organizations/org_01HZ3K8VPNQ4RJXEMYVWCT9BS1/members/mem_01HZ5P2WQRS6TLUCADYG3EN4X8 \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..."

GET/api/v1/orgGet Current Org SettingsBearer Token▾

Retrieve settings for the organization derived from the authenticated JWT context. Requires the org:read permission. The organization is resolved via OrgContextGuard — no orgId path parameter is needed.

Response Fields

Name	Type	Required	Description
`id`	string (UUID)	Optional	Organization unique identifier.
`name`	string	Optional	Display name.e.g. `Acme Corp`
`slug`	string	Optional	URL-safe identifier.e.g. `acme-corp`
`domain`	string \| null	Optional	Primary domain.
`plan`	string	Optional	Subscription plan.e.g. `PRO`
`status`	string	Optional	Organization status.e.g. `ACTIVE`
`settings`	Record<string, string>	Optional	Arbitrary key-value organization settings.
`createdAt`	string (ISO 8601)	Optional	Creation timestamp.
`updatedAt`	string (ISO 8601)	Optional	Last update timestamp.

Response Example

{
  "id": "org_01HZ3K8VPNQ4RJXEMYVWCT9BS1",
  "name": "Acme Corp",
  "slug": "acme-corp",
  "domain": "acme.com",
  "plan": "PRO",
  "status": "ACTIVE",
  "logoUrl": "https://cdn.acme.com/logo.png",
  "primaryColor": "#0057FF",
  "allowedDomains": [
    "acme.com"
  ],
  "maxMembers": 100,
  "maxApplications": 20,
  "settings": {
    "mfaRequired": "true",
    "sessionTimeoutSeconds": "3600",
    "passwordPolicy": "strong"
  },
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-06-01T08:00:00.000Z"
}

Code Examples

curl -X GET https://api.sutraid.com/api/v1/org \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..."

PUT/api/v1/orgUpdate Current Org SettingsBearer Token▾

Update settings for the organization derived from the authenticated JWT context. Requires the org:update permission. Partial updates are supported — only provided fields are modified.

Request Body

Name	Type	Required	Description
`name`	string	Optional	New display name for the organization.e.g. `Acme Corp (Updated)`
`settings`	Record<string, string>	Optional	Arbitrary key-value settings to store for the organization. Merged with existing settings.e.g. `{ "mfaRequired": "true", "sessionTimeoutSeconds": "1800" }`

Response Fields

Name	Type	Required	Description
`id`	string (UUID)	Optional	Organization unique identifier.
`name`	string	Optional	Updated display name.e.g. `Acme Corp (Updated)`
`settings`	Record<string, string>	Optional	Updated key-value settings map.
`updatedAt`	string (ISO 8601)	Optional	Timestamp of the update.

Response Example

{
  "id": "org_01HZ3K8VPNQ4RJXEMYVWCT9BS1",
  "name": "Acme Corp (Updated)",
  "slug": "acme-corp",
  "domain": "acme.com",
  "plan": "PRO",
  "status": "ACTIVE",
  "logoUrl": "https://cdn.acme.com/logo.png",
  "primaryColor": "#0057FF",
  "allowedDomains": [
    "acme.com"
  ],
  "maxMembers": 100,
  "maxApplications": 20,
  "settings": {
    "mfaRequired": "true",
    "sessionTimeoutSeconds": "1800",
    "passwordPolicy": "strong"
  },
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-06-10T12:45:00.000Z"
}

Code Examples

curl -X PUT https://api.sutraid.com/api/v1/org \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp (Updated)",
    "settings": {
      "mfaRequired": "true",
      "sessionTimeoutSeconds": "1800"
    }
  }'