# Join an Organization Component

PropelAuth's Join an Organization component can be used in tandem with the [Create Organization](https://ui.propelauth.com/org-components/create-org) component when your user has a [Login State](https://ui.propelauth.com/login-signup-apis#login-state) of `USER_MUST_BE_IN_AT_LEAST_ONE_ORG`. If their email domain matches the domain of an organization that is joinable, that organization will be available for the user to join.

We highly recommend reviewing the [Login and Signup Guide](https://ui.propelauth.com/login-signup-apis) if using any of our login or signup components.

## Join an Organization

Select the organization you'd like to join. Based on your email address, you can join any of the orgs in the dropdown below.

- Acme Inc
- Skynet
- Aperture Science

Join Organization

---

## [Shadcn Installation](https://ui.propelauth.com/login-signup-apis/join-an-organization#shadcn-installation)

Install this component from our [shadcn registry](https://ui.propelauth.com/getting-started/component-registry).

```bash
npx shadcn@latest add https://components.propelauth.com/r/join-an-organization.json
```

---

# Reference APIs

These are the APIs that are used by the above component. You can use these APIs directly in your own code.

## [fetchJoinableOrgs](https://ui.propelauth.com/login-signup-apis/join-an-organization#fetch-joinable-orgs)

Returns an array of organizations that the user can join based on their email domain.

### Success Response

- Name `orgs`
  - Type JoinableOrg[]
  - Description An array of objects that include the following:
    - **id**: The ID of the organization.
    - **name**: The name of the organization.

### Response Functions

The response object has a **handle** function that you can use to handle the response. These functions can be async, and you can return values from them.

- Name `success`
  - Description Successful request.
- Name `orgsNotEnabled`
  - Description Organizations are not enabled in the PropelAuth Dashboard.
- Name `unexpectedOrUnhandled`
  - Description An unexpected error occurred.

### Request

```javascript
const { fetchJoinableOrgs } = useAuthFrontendApis()

const response = await fetchJoinableOrgs()
response.handle({
    success(data) {
        console.log(data.orgs)
    },
    orgsNotEnabled(error) {
        console.error('Organizations are disabled', error)
    },
    unexpectedOrUnhandled(error) {
        console.error('Unexpected or unhandled', error.user_facing_error)
    },
})
```

### Successful Response

```json
{
    "orgs": [
        {
            "id": "org_123",
            "name": "Acme Corp"
        },
        {
            "id": "org_456",
            "name": "Widget Co"
        }
    ]
}
```

## [joinOrg](https://ui.propelauth.com/login-signup-apis/join-an-organization#join-org)

Adds the logged in user as a member of the provided organization.

### Arguments

- Name `org_id` *
  - Type string
  - Description The ID of the org to join.

### Success Response

- Name `org_id`
  - Type string
  - Description The ID of the org.
- Name `first_org`
  - Type boolean
  - Description If the org is the first org the user belongs to.

### Response Functions

The response object has a **handle** function that you can use to handle the response. These functions can be async, and you can return values from them.

- Name `success`
  - Description Successful request.
- Name `userAlreadyInTooManyOrgs`
  - Description User already belongs to the maximum amount of orgs.
- Name `orgMaxUsersLimitExceeded`
  - Description The org's user limit has already been met.
- Name `orgsNotEnabled`
  - Description Organizations are not enabled for the project.
- Name `orgNotFound`
  - Description The org ID cannot be found.
- Name `unexpectedOrUnhandled`
  - Description An unexpected error occurred.

### Request

```javascript
const { joinOrg } = useAuthFrontendApis()

const response = await joinOrg("1189c444-8a2d-4c41-8b4b-ae43ce79a492")
response.handle({
    success(data) {
        console.log("User added to org: ", data.org_id)
    },
    orgNotFound(error) {
        console.error('Org not found', error)
    },
    orgsNotEnabled(error) {
        console.error('Org not enabled', error)
    },
    userAlreadyInTooManyOrgs(error) {
        console.error('User already in too many orgs', error)
    },
    orgMaxUsersLimitExceeded(error) {
        console.error('Org max users limit exceeded', error)
    },
    unexpectedOrUnhandled(error) {
        console.error('Unexpected or unhandled error', error)
    },
})
```

### Successful Response

```json
{
    "org_id": "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
    "first_org": true
}
```