Skip to main content

Organization management

Use Clerk's Android Organization APIs to create and manage Organizations, switch the , and build custom Organization flows. Organization methods return ClerkResult, so handle both ClerkResult.Success and ClerkResult.Failure.

import com.clerk.api.network.serialization.ClerkResult
import com.clerk.api.organizations.Organization

when (val result = Organization.create(name = "Acme", slug = "acme")) {
    is ClerkResult.Success -> {
        val organization = result.value
    }
    is ClerkResult.Failure -> {
        // Show an error state.
    }
}

Active organization

The is stored on Session.lastActiveOrganizationId for the current session. Use Clerk.organization to read the Active Organization and Clerk.organizationMembership to read the signed-in user's Active Organization membership.

Use Clerk.auth.setActive() to switch the for a session. Pass sessionId and organizationId to select an Organization, or omit organizationId (or pass null) to select the user's . The latter isn't allowed when Clerk.organizationSelectionIsForced is true.

Select an Organization

val sessionId = Clerk.session?.id ?: return

when (
    val result = Clerk.auth.setActive(
        sessionId = sessionId,
        organizationId = "org_123",
    )
) {
    is ClerkResult.Success -> {
        val session = result.value
    }
    is ClerkResult.Failure -> {
        // Handle the failure.
    }
}

Select the Personal Account

val sessionId = Clerk.session?.id ?: return

when (val result = Clerk.auth.setActive(sessionId = sessionId)) {
    is ClerkResult.Success -> {
        val personalAccountSession = result.value
    }
    is ClerkResult.Failure -> {
        // Handle the failure.
    }
}

Organization

Organization represents a Clerk Organization and provides helpers for profile, role, membership, invitation, request, and domain management.

Create or get an Organization

when (val result = Organization.create(name = "Acme", slug = "acme")) {
    is ClerkResult.Success -> {
        val organization = result.value
    }
    is ClerkResult.Failure -> {
        // Handle the failure.
    }
}

when (val result = Organization.get(id = "org_123")) {
    is ClerkResult.Success -> {
        val organization = result.value
    }
    is ClerkResult.Failure -> {
        // Handle the failure.
    }
}

Update an Organization

when (val result = organization.update(name = "Acme, Inc.", slug = "acme-inc")) {
    is ClerkResult.Success -> {
        val updatedOrganization = result.value
    }
    is ClerkResult.Failure -> {
        // Handle the failure.
    }
}

Delete an Organization

when (val result = organization.delete()) {
    is ClerkResult.Success -> {
        val deletedObject = result.value
    }
    is ClerkResult.Failure -> {
        // Handle the failure.
    }
}
when (val result = organization.updateLogo(file = logoFile)) {
    is ClerkResult.Success -> {
        val updatedOrganization = result.value
    }
    is ClerkResult.Failure -> {
        // Handle the failure.
    }
}

when (val result = organization.deleteLogo()) {
    is ClerkResult.Success -> {
        val updatedOrganization = result.value
    }
    is ClerkResult.Failure -> {
        // Handle the failure.
    }
}

Reload an Organization

when (val result = organization.reload()) {
    is ClerkResult.Success -> {
        val refreshedOrganization = result.value
    }
    is ClerkResult.Failure -> {
        // Handle the failure.
    }
}

List Roles

when (val result = organization.getRoles()) {
    is ClerkResult.Success -> {
        val roles = result.value
    }
    is ClerkResult.Failure -> {
        // Handle the failure.
    }
}

when (val result = organization.getRolesPaginated(limit = 20, offset = 0)) {
    is ClerkResult.Success -> {
        val roles = result.value.data
        val totalCount = result.value.totalCount
    }
    is ClerkResult.Failure -> {
        // Handle the failure.
    }
}

Memberships

Use membership APIs to list members, add members, update Roles, remove members, and check Organization Permissions.

List Organization memberships

when (
    val result = organization.getOrganizationMemberships(
        query = "jane",
        role = "org:member",
        limit = 20,
        offset = 0,
    )
) {
    is ClerkResult.Success -> {
        val memberships = result.value.data
    }
    is ClerkResult.Failure -> {
        // Handle the failure.
    }
}

Create or remove a membership

when (val result = organization.createMembership(role = "org:member", userId = userId)) {
    is ClerkResult.Success -> {
        val organizationMembership = result.value
    }
    is ClerkResult.Failure -> {
        // Handle the failure.
    }
}

when (val result = organization.removeMember(userId = userId)) {
    is ClerkResult.Success -> {
        val removedMembership = result.value
    }
    is ClerkResult.Failure -> {
        // Handle the failure.
    }
}

Update or delete a membership

OrganizationMembership also provides helpers for updating a member's role in the Organization and deleting the membership.

when (val result = organizationMembership.updateMembership(userId = userId, role = "org:admin")) {
    is ClerkResult.Success -> {
        val updatedMembership = result.value
    }
    is ClerkResult.Failure -> {
        // Handle the failure.
    }
}

when (val result = organizationMembership.delete()) {
    is ClerkResult.Success -> {
        val deletedObject = result.value
    }
    is ClerkResult.Failure -> {
        // Handle the failure.
    }
}

Check membership Permissions

OrganizationMembership provides the hasPermission() method, along with the convenience properties below for checking Clerk System Permissions:

  • canManageProfile
  • canDeleteOrganization
  • canReadMemberships
  • canManageMemberships
  • canReadDomains
  • canManageDomains
  • canReadBilling
  • canManageBilling
  • canReadApiKeys
  • canManageApiKeys
if (organizationMembership.canManageMemberships) {
    // Show member management actions.
}

if (organizationMembership.hasPermission("org:sys_domains:manage")) {
    // Show domain management actions.
}

Invitations

Use invitation APIs to invite users to an Organization, list invitations, bulk-create invitations, and revoke invitations.

Create or list invitations

when (
    val result = organization.createInvitation(
        emailAddress = "new@acme.com",
        role = "org:member",
    )
) {
    is ClerkResult.Success -> {
        val invitation = result.value
    }
    is ClerkResult.Failure -> {
        // Handle the failure.
    }
}

when (
    val result = organization.getInvitations(
        limit = 20,
        offset = 0,
        status = OrganizationInvitation.Status.Pending,
    )
) {
    is ClerkResult.Success -> {
        val invitations = result.value.data
    }
    is ClerkResult.Failure -> {
        // Handle the failure.
    }
}

Bulk-create invitations

when (
    val result = organization.bulkCreateInvitations(
        emailAddresses = listOf("one@acme.com", "two@acme.com"),
        role = "org:member",
    )
) {
    is ClerkResult.Success -> {
        val invitations = result.value
    }
    is ClerkResult.Failure -> {
        // Handle the failure.
    }
}

Revoke an invitation

OrganizationInvitation also provides a helper for revoking an invitation.

when (val result = invitation.revoke()) {
    is ClerkResult.Success -> {
        val revokedInvitation = result.value
    }
    is ClerkResult.Failure -> {
        // Handle the failure.
    }
}

Membership Requests

Use Membership Request APIs to list, accept, and reject requests to join an Organization.

List Membership Requests

when (val result = organization.getMembershipRequests(limit = 20, offset = 0, status = "pending")) {
    is ClerkResult.Success -> {
        val requests = result.value.data
    }
    is ClerkResult.Failure -> {
        // Handle the failure.
    }
}

Accept or reject a Membership Request

OrganizationMembershipRequest also provides helpers for accepting and rejecting Membership Requests.

when (val result = membershipRequest.accept()) {
    is ClerkResult.Success -> {
        val acceptedRequest = result.value
    }
    is ClerkResult.Failure -> {
        // Handle the failure.
    }
}

when (val result = membershipRequest.reject()) {
    is ClerkResult.Success -> {
        val rejectedRequest = result.value
    }
    is ClerkResult.Failure -> {
        // Handle the failure.
    }
}

Domains

Use Organization domain APIs to create, list, retrieve, verify, update, and delete Verified Domains.

Create or list domains

when (val result = organization.createDomain(name = "acme.com")) {
    is ClerkResult.Success -> {
        val domain = result.value
    }
    is ClerkResult.Failure -> {
        // Handle the failure.
    }
}

when (val result = organization.getDomains(limit = 20, offset = 0)) {
    is ClerkResult.Success -> {
        val domains = result.value.data
    }
    is ClerkResult.Failure -> {
        // Handle the failure.
    }
}

Get or delete a domain

when (val result = organization.getDomain(domainId = domainId)) {
    is ClerkResult.Success -> {
        val domain = result.value
    }
    is ClerkResult.Failure -> {
        // Handle the failure.
    }
}

when (val result = organization.deleteDomain(domainId = domainId)) {
    is ClerkResult.Success -> {
        val deletedObject = result.value
    }
    is ClerkResult.Failure -> {
        // Handle the failure.
    }
}

OrganizationDomain also provides helpers for deleting a domain, verifying affiliation, and updating the enrollment mode.

  • domain.delete()
  • domain.prepareAffiliationVerification(affiliationEmailAddress)
  • domain.attemptAffiliationVerification(code)
  • domain.sendEmailCode(affiliationEmailAddress)
  • domain.verifyCode(code)
  • domain.updateEnrollmentMode(enrollmentMode, deletePending)

Delete a domain

Use domain.delete() when you already have an OrganizationDomain instance. To delete a domain directly from the parent Organization by ID, use organization.deleteDomain() instead.

when (val result = domain.delete()) {
    is ClerkResult.Success -> {
        val deletedObject = result.value
    }
    is ClerkResult.Failure -> {
        // Handle the failure.
    }
}

Prepare or attempt affiliation verification

when (val result = domain.prepareAffiliationVerification(affiliationEmailAddress = "admin@acme.com")) {
    is ClerkResult.Success -> {
        val preparedDomain = result.value
    }
    is ClerkResult.Failure -> {
        // Handle the failure.
    }
}

when (val result = domain.attemptAffiliationVerification(code = "123456")) {
    is ClerkResult.Success -> {
        val verifiedDomain = result.value
    }
    is ClerkResult.Failure -> {
        // Handle the failure.
    }
}

Send and verify a domain email code

when (val result = domain.sendEmailCode(affiliationEmailAddress = "admin@acme.com")) {
    is ClerkResult.Success -> {
        val preparedDomain = result.value
    }
    is ClerkResult.Failure -> {
        // Handle the failure.
    }
}

when (val result = domain.verifyCode(code = "123456")) {
    is ClerkResult.Success -> {
        val verifiedDomain = result.value
    }
    is ClerkResult.Failure -> {
        // Handle the failure.
    }
}

Update a domain's enrollment mode

when (
    val result = domain.updateEnrollmentMode(
        enrollmentMode = OrganizationDomain.EnrollmentMode.AutomaticInvitation,
        deletePending = false,
    )
) {
    is ClerkResult.Success -> {
        val updatedDomain = result.value
    }
    is ClerkResult.Failure -> {
        // Handle the failure.
    }
}

User Organization helpers

User also provides helpers for listing Organization invitations, suggestions, memberships, and creation defaults. Companion methods on User fetch data for the current session, and instance methods on user do the same for that user.

List Organization invitations

when (val result = User.getOrganizationInvitations(limit = 20, offset = 0, status = "pending")) {
    is ClerkResult.Success -> {
        val invitations = result.value.data
    }
    is ClerkResult.Failure -> {
        // Handle the failure.
    }
}

when (val result = user.getOrganizationInvitations(limit = 20, offset = 0, status = "pending")) {
    is ClerkResult.Success -> {
        val invitations = result.value.data
    }
    is ClerkResult.Failure -> {
        // Handle the failure.
    }
}

UserOrganizationInvitation also provides a helper for accepting an invitation.

when (val result = userOrganizationInvitation.accept()) {
    is ClerkResult.Success -> {
        val acceptedInvitation = result.value
    }
    is ClerkResult.Failure -> {
        // Handle the failure.
    }
}

List Organization suggestions

when (val result = User.getOrganizationSuggestions(limit = 20, offset = 0, status = "pending")) {
    is ClerkResult.Success -> {
        val suggestions = result.value.data
    }
    is ClerkResult.Failure -> {
        // Handle the failure.
    }
}

when (val result = user.getOrganizationSuggestions(statuses = listOf("pending"))) {
    is ClerkResult.Success -> {
        val suggestions = result.value.data
    }
    is ClerkResult.Failure -> {
        // Handle the failure.
    }
}

OrganizationSuggestion also provides a helper for accepting a suggestion.

when (val result = organizationSuggestion.accept()) {
    is ClerkResult.Success -> {
        val acceptedSuggestion = result.value
    }
    is ClerkResult.Failure -> {
        // Handle the failure.
    }
}

List Organization memberships

when (val result = user.getOrganizationMemberships(limit = 20, offset = 0)) {
    is ClerkResult.Success -> {
        val memberships = result.value.data
    }
    is ClerkResult.Failure -> {
        // Handle the failure.
    }
}

Get Organization creation defaults

when (val result = user.getOrganizationCreationDefaults()) {
    is ClerkResult.Success -> {
        val creationDefaults = result.value
    }
    is ClerkResult.Failure -> {
        // Handle the failure.
    }
}

Feedback

What did you think of this content?

Last updated on

GitHubEdit on GitHub