# Organization management

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

```kotlin
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 Active Organization is stored on `Session.lastActiveOrganizationId` for the current session. Use [Clerk.organization](https://clerk.com/docs/android/reference/native-mobile/clerk.md#access-the-active-organization-state) 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 Active Organization for a session. Pass `sessionId` and `organizationId` to select an Organization, or omit `organizationId` (or pass `null`) to select the user's Personal Account. The latter isn't allowed when `Clerk.organizationSelectionIsForced` is `true`.

### Select an Organization

```kotlin
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

```kotlin
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

```kotlin
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

```kotlin
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

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

### Manage the Organization logo

```kotlin
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

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

### List Roles

```kotlin
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

```kotlin
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

```kotlin
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.

```kotlin
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](https://clerk.com/docs/guides/organizations/control-access/roles-and-permissions.md?sdk=android#system-permissions):

- `canManageProfile`
- `canDeleteOrganization`
- `canReadMemberships`
- `canManageMemberships`
- `canReadDomains`
- `canManageDomains`
- `canReadBilling`
- `canManageBilling`
- `canReadApiKeys`
- `canManageApiKeys`

```kotlin
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

```kotlin
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

```kotlin
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.

```kotlin
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

```kotlin
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.

```kotlin
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

```kotlin
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

```kotlin
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()](https://clerk.com/docs/android/reference/native-mobile/organizations.md#get-or-delete-a-domain) instead.

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

### Prepare or attempt affiliation verification

```kotlin
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

```kotlin
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

```kotlin
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

```kotlin
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.

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

### List Organization suggestions

```kotlin
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.

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

### List Organization memberships

```kotlin
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

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

---

## Sitemap

[Overview of all docs pages](https://clerk.com/docs/llms.txt)