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,

        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"],
            }
        },

        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

Request

auth.addUserToOrg({
    userId: "31c41c16-c281-44ae-9602-8a047e3bf33d",
    orgId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
    role: "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

Request

auth.inviteUserToOrg({
    email: "test@propelauth.com",
    orgId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
    role: "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

Request

auth.changeUserRoleInOrg({
    userId: "31c41c16-c281-44ae-9602-8a047e3bf33d",
    orgId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
    role: "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