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",
urlSafeOrgSlug: "fa5514e1-c81...",
isSamlConfigured: false,
isSamlInTestMode: false,
canSetupSaml: true,
domain: "acme.com",
domainAutojoin: false,
domainRestrict: false,
maxUsers: undefined,
customRoleMappingName: "Paid Plan",
legacyOrgId: "1234",
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,
customRoleMappingName: "Paid Plan",
legacyOrgId: "1234",
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
orgIdToOrgInfo: {
"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.
- Name
customRoleMappingName- Type
- string
- Description
- The name of the custom role and permissions configuration.
- Name
legacyOrgId- Type
- string
- Description
- The org's ID in a previous system. This ID will be stored on the org as a legacyOrgId and it is present everywhere orgId's are (e.g. fetching org metadata).
Request
auth.createOrg({
name: "Acme Inc",
domain: "acme.com",
enableAutoJoiningByDomain: true,
membersMustHaveMatchingDomain: true,
maxUsers: 100,
legacyOrgId: "1234",
customRoleMappingName: "Business Plan"
})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
POST/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
POST/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
GET/api/backend/v1/custom_role_mappings
Fetch Role Mappings
Fetches roles and permissions mappings.
Properties
Request
auth.fetchCustomRoleMappings()Successful Response
{
customRoleMappings: [
{
customRoleMappingName: "Free Plan",
numOrgsSubscribed: 2
},
{
customRoleMappingName: "Paid Plan",
numOrgsSubscribed: 10
}
]
}PUT/api/backend/v1/org/<orgId>
Subscribe Org to Role Mapping
Subscribes an organization to a Role Mapping.
Properties
- Name
orgId*- Type
- string
- Description
- The organization ID
- Name
customRoleMappingName*- Type
- string
- Description
- The name of the Role Configuration.
Request
auth.subscribeOrgToRoleMapping({
orgId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
customRoleMappingName: "Paid Plan"
})Successful Response
GET/api/backend/v1/pending_org_invites
Fetch Pending Invites
Fetches pending invites for orgs 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
orgId- Type
- string
- Description
- The organization's ID
Request
auth.fetchPendingInvites({
pageSize: 10,
pageNumber: 0,
orgId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492"
})Successful Response
{
invites: [{
inviteeEmail: "test@propelauth.com",
orgId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
orgName: "Acme Inc",
roleInOrg: "Member",
additionalRolesInOrg: [],
createdAt: 1718648493,
expiresAt: 1719080493,
inviterEmail: "owner@propelauth.com",
inviterUserId: "31c41c16-c281-44ae-9602-8a047e3bf33d"
}],
totalInvites: 1,
pageSize: 10,
currentPage: 0,
hasMoreResults: false
}DELETE/api/backend/v1/pending_org_invites
Revoke Pending Org Invite
Deletes a user invite to an organization.
Properties
- Name
orgId*- Type
- string
- Description
- The organization ID
- Name
inviteeEmail*- Type
- string
- Description
- The email address of the invitee
Request
auth.revokePendingOrgInvite({
orgId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
inviteeEmail: "example@propelauth.com"
})Successful Response
POST/api/backend/v1/org/<orgId>/create_saml_connection_link
Create SAML Connection Link
Creates a link that allows a user to setup SAML for an organization without logging in or creating an account. Visit our SAML/Enterprise SSO docs for more information.
Properties
- Name
orgId*- Type
- string
- Description
- The organization ID
- Name
expiresInSeconds- Type
- number
- Description
- The amount of seconds before the link expires
Request
auth.createOrgSamlConnectionLink(
"1189c444-8a2d-4c41-8b4b-ae43ce79a492", // orgId
86400, // expired in seconds
)Successful Response
{
url: "https://example.com"
}