Organization API Reference
These APIs can be called from your backend using your PropelAuth API Key.
GET/api/backend/v1/org/<orgId>
Fetch Org
Fetches an organization by ID
Properties
- Name
orgId*- Type
- string
- Description
- The organization's ID
Request
auth.fetchOrg("1189c444-8a2d-4c41-8b4b-ae43ce79a492")Successful Response
{
orgId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
name: "Acme Inc",
isSamlConfigured: false,
maxUsers: undefined,
metadata: {
customKey: "customValue"
},
}POST/api/backend/v1/org/query
Fetch Orgs
Fetches organizations with optional filtering
Properties
- Name
pageSize- Type
- number
- Description
- The number of organizations to return per page
- Name
pageNumber- Type
- number
- Description
- The page number to return
- Name
orderBy- Type
- string
- Description
- An enum value to order the organizations by. Possible values include CREATED_AT_ASC, CREATED_AT_DESC, NAME
- Name
name- Type
- string
- Description
- A name to search for. We'll return any organizations whose name contains this value
Request
auth.fetchOrgByQuery({
pageSize: 10,
pageNumber: 0,
orderBy: "CREATED_AT_ASC",
name: "acme"
})Successful Response
{
orgs: [{
orgId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
name: "Acme Inc",
isSamlConfigured: false,
maxUsers: undefined,
metadata: {
customKey: "customValue"
},
}],
totalOrgs: 1,
pageSize: 10,
currentPage: 0,
hasMoreResults: false
}GET/api/backend/v1/user/org/<orgId>
Fetch Users in Org
Fetches users within an organization
Properties
- Name
orgId*- Type
- string
- Description
- The ID of the organization to fetch users for
- Name
includeOrgs- Type
- boolean
- Description
- Whether to include all organizations the user is in in the response
- Name
role- Type
- string
- Description
- Only return users with this role within the organization. This is case sensitive.
- Name
pageSize- Type
- number
- Description
- The number of users to return per page
- Name
pageNumber- Type
- number
- Description
- The page number to return
Request
auth.fetchUsersInOrg({
orgId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
role: "Admin"
includeOrgs: false,
pageSize: 10,
pageNumber: 0,
})Successful Response
{
users: [{
userId: "31c41c16-c281-44ae-9602-8a047e3bf33d",
email: "test@example.com",
emailConfirmed: true,
firstName: "Buddy",
lastName: "Framm",
username: "airbud3",
pictureUrl: "https://example.com/picture.png",
properties: {
favoriteSport: "basketball"
},
locked: false,
enabled: true,
hasPassword: true,
updatePasswordRequired: false,
mfaEnabled: false,
canCreateOrgs: false,
createdAt: 1625476380,
lastActiveAt: 1625476380,
// Only returned if includeOrgs is true
orgIdToOrgMemberInfo: {
"1189c444-8a2d-4c41-8b4b-ae43ce79a492": {
orgId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
orgName: "Acme Inc",
orgMetadata: {
customKey: "customValue"
},
userRole: "Admin",
userPermissions: ["CanViewBilling"],
urlSafeOrgName: "acme-inc",
inheritedUserRolesPlusCurrentRole: ["Admin", "Member"],
orgRoleStructure: "multi_role",
additionalRoles: [
"Member"
],
}
},
legacyUserId: "thisIsSetWhenYouMigrateFromAnExternalSource",
}],
totalUsers: 1,
currentPage: 0,
pageSize: 10,
hasMoreResults: false,
}POST/api/backend/v1/org/
Create Org
Creates a new organization. Your users can use our hosted pages to create new organizations, but you can also use this API to create organizations programmatically.
Properties
- Name
name*- Type
- string
- Description
- The name of the organization. This can only include alphanumeric characters, spaces, and underscores.
- Name
domain- Type
- string
- Description
- The domain of the organization.
- Name
enableAutoJoiningByDomain- Type
- boolean
- Description
- Whether users can automatically join the organization if their email address matches the organization domain. If this is true, you must also set the domain property.
- Name
membersMustHaveMatchingDomain- Type
- boolean
- Description
- Whether users will not be able to join the organization unless their email address matches the organization domain. If this is true, you must also set the domain property.
- Name
maxUsers- Type
- number
- Description
- The maximum number of users allowed in the organization. If not set, there is no limit.
Request
auth.createOrg({
name: "Acme Inc",
domain: "acme.com",
enableAutoJoiningByDomain: true,
membersMustHaveMatchingDomain: true,
maxUsers: 100,
})Successful Response
{
orgId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
name: "Acme Inc",
}POST/api/backend/v1/org/add_user
Add User to Org
Adds a user to an organization with the specified role. Unlike the org invitation API, this API does not send an invitation email to the user. The user will in the organization immediately.
Properties
- Name
userId*- Type
- string
- Description
- The user's ID
- Name
orgId*- Type
- string
- Description
- The organization ID
- Name
role*- Type
- string
- Description
- The role the user should have in the organization
- Name
additionalRoles- Type
- string[]
- Description
- Additional roles that the user should have in the organization. This is only available when multi-role support is enabled.
Request
auth.addUserToOrg({
userId: "31c41c16-c281-44ae-9602-8a047e3bf33d",
orgId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
role: "Admin",
additionalRoles: ["Member"]
})Successful Response
{}POST/api/backend/v1/invite_user
Invite User to Org
Sends an invitation to a user to join an organization with the specified role. The user will receive an email with a link to accept the invitation. The user will not be added to the organization until they accept the invitation.
Properties
- Name
email*- Type
- string
- Description
- The user's email address
- Name
orgId*- Type
- string
- Description
- The organization ID
- Name
role*- Type
- string
- Description
- The role the user should have in the organization
- Name
additionalRoles- Type
- string[]
- Description
- Additional roles that the user should have in the organization. This is only available when multi-role support is enabled.
Request
auth.inviteUserToOrg({
email: "test@propelauth.com",
orgId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
role: "Admin",
additionalRoles: ["Member"]
})Successful Response
GET/api/backend/v1/org/change_role
Change Role
Change a user's role in an organization. The user must already be a member of the organization.
Properties
- Name
userId*- Type
- string
- Description
- The user's ID
- Name
orgId*- Type
- string
- Description
- The organization ID
- Name
role*- Type
- string
- Description
- The role the user should have in the organization
- Name
additionalRoles- Type
- string[]
- Description
- Additional roles that the user should have in the organization. This is only available when multi-role support is enabled.
Request
auth.changeUserRoleInOrg({
userId: "31c41c16-c281-44ae-9602-8a047e3bf33d",
orgId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
role: "Admin",
additionalRoles: ["Member"]
})Successful Response
{}POST/api/backend/v1/org/remove_user
Remove User from Org
Remove a user from an organization.
Properties
- Name
userId*- Type
- string
- Description
- The user's ID
- Name
orgId*- Type
- string
- Description
- The organization ID
Request
auth.removeUserFromOrg({
userId: "31c41c16-c281-44ae-9602-8a047e3bf33d",
orgId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
})Successful Response
{}PUT/api/backend/v1/org/<orgId>
Update Org
Updates an organization.
Properties
- Name
orgId*- Type
- string
- Description
- The organization ID
- Name
name- Type
- string
- Description
- The name of the organization. This can only include alphanumeric characters, spaces, and underscores.
- Name
domain- Type
- string
- Description
- The domain of the organization.
- Name
enableAutoJoiningByDomain- Type
- boolean
- Description
- Whether users can automatically join the organization if their email address matches the organization domain. If this is true, you must also set the domain property.
- Name
membersMustHaveMatchingDomain- Type
- boolean
- Description
- Whether users will not be able to join the organization unless their email address matches the organization domain. If this is true, you must also set the domain property.
- Name
maxUsers- Type
- number
- Description
- The maximum number of users allowed in the organization. If not set, there is no limit.
- Name
canSetupSaml- Type
- boolean
- Description
- Whether users can set up SAML for the organization.
- Name
metadata- Type
- { [key: string]: any }
- Description
- A JSON object containing any metadata you want to store about the organization.
Request
auth.updateOrg({
orgId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
name: "Acme Inc",
domain: "acme.com",
enableAutoJoiningByDomain: true,
membersMustHaveMatchingDomain: true,
maxUsers: 100,
canSetupSaml: true,
metadata: {
customKey: "customValue",
},
})Successful Response
DELETE/api/backend/v1/org/<orgId>
Delete Org
Deletes an organization.
Properties
- Name
orgId*- Type
- string
- Description
- The organization ID
Request
auth.deleteOrg("1189c444-8a2d-4c41-8b4b-ae43ce79a492")Successful Response
POST/api/backend/v1/org/<orgId>/allow_saml
Enable SAML for Org
Allows an organization to setup SAML SSO. Users in the organization will then be able to go through the SAML setup flow.
Properties
- Name
orgId*- Type
- string
- Description
- The organization ID
Request
auth.allowOrgToSetupSamlConnection(
"1189c444-8a2d-4c41-8b4b-ae43ce79a492"
)Successful Response
GET/api/backend/v1/org/<orgId>/disallow_saml
Disable SAML for Org
Disallows an organization to setup SAML SSO. If the organization already has SAML setup, they will no longer be able to use it.
Properties
- Name
orgId*- Type
- string
- Description
- The organization ID
Request
auth.disallowOrgToSetupSamlConnection(
"1189c444-8a2d-4c41-8b4b-ae43ce79a492"
)Successful Response