Logo
Frontend
Backend 

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
  • Name
    domain
    Type
    string
    Description
    A domain to search for. We'll return any organizations whose domain matches this value

Request

auth.fetchOrgByQuery({
    pageSize: 10,
    pageNumber: 0,
    orderBy: "CREATED_AT_ASC",
    name: "acme",
    domain: "example.com"
})

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"
}
    GET/api/backend/v1/saml_sp_metadata/<orgId>

    Fetch SAML SP Metadata

    Fetches SAML Service Provider Metadata. This is the information your organizations will input into their IdP when configuring SAML.

    Properties

    • Name
      orgId *
      Type
      string
      Description
      The ID of the organization

    Request

    auth.fetchSamlSpMetadata("1189c444-8a2d-4c41-8b4b-ae43ce79a492")

    Successful Response

    {
    entityId: "https://auth.your.domain/saml/ORGS-URL-SLUG/metadata",
    acsUrl: "https://auth.your.domain/saml/ORGS-URL-SLUG/acs",
    logoutUrl: "https://auth.your.domain/saml/ORGS-URL-SLUG/logout"
}
    POST/api/backend/v1/saml_idp_metadata

    Set SAML IdP Metadata

    Sets the SAML metadata from an organization's IdP. Must be completed before using the SAML Go Live endpoint.

    Properties

    • Name
      idpEntityId *
      Type
      string
      Description
      The Entity ID (also known as Identity Provider Issuer) from the organization's IdP
    • Name
      idpSsoUrl *
      Type
      string
      Description
      The Single Sign-On URL from the organization's IdP
    • Name
      idpCertificate *
      Type
      string
      Description
      The Base-64 encoded X.509 certificate from the organization's IdP
    • Name
      provider *
      Type
      string
      Description
      The name of the SAML provider. Must equal 'Google', 'Rippling', 'OneLogin', 'JumpCloud', 'Okta', 'Azure', 'Duo', or 'Generic'

    Request

    auth.setSamlIdpMetadata(orgId, {
    idpEntityId: "https://sts.windows.net/SOME-UUID/",
    idpSsoUrl: "https://login.microsoftonline.com/SOME-UUID/saml2",
    idpCertificate: "-----BEGIN CERTIFICATE-----MyCertificateHere-----END CERTIFICATE-----",
    provider: "Azure"
});

    Successful Response

    POST/api/backend/v1/saml_idp_metadata/go_live/<orgId>

    Enable SAML Connection

    Sets an organization's SAML status to Live after using the Set SAML IdP Metadata endpoint

    Properties

    • Name
      orgId *
      Type
      string
      Description
      The organization ID

    Request

    auth.samlGoLive(
    "1189c444-8a2d-4c41-8b4b-ae43ce79a492"
)

    Successful Response

    DELETE/api/backend/v1/saml_idp_metadata/<orgId>

    Delete SAML Connection

    Deletes an organization's SAML connection.

    Properties

    • Name
      orgId *
      Type
      string
      Description
      The organization ID

    Request

    auth.deleteSamlConnection("1189c444-8a2d-4c41-8b4b-ae43ce79a492")

    Successful Response